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PenPoint Application Writing Guide provides a tutorial on writing PenPoint 
applications, including many coding samples. This is the first book you should 
read as a beginning PenPoint applications developer. 

PenPoint Architectural Reference Volume I presents the concepts of the fun- 
damental PenPoint classes. Read this book when you need to understand the 
fundamental PenPoint subsystems, such as the class manager, application 
framework, windows and graphics, and so on. 

PenPoint Architectural Reference Volume II presents the concepts of the 
supplemental PenPoint classes. You should read this book when you need 
to understand the supplemental PenPoint subsystems, such as the text sub- 
system, the file system, connectivity, and so on. 

PenPoint API Reference Volume I provides a complete reference to the 
fundamental PenPoint classes, messages, and data structures. 

PenPoint API Reference Volume II provides a complete reference to the 
supplemental PenPoint classes, messages, and data structures. 

PenPoint User Interface Design Reference describes the elements of the 
PenPoint Notebook User Interface, sets standards for using those elements, 
and describes how PenPoint uses the elements. Read this book before 
designing your application's user interface. 

PenPoint Development Tools describes the environment for developing, de- 
bugging, and testing PenPoint applications. You need this book when you 
start to implement and test your first PenPoint application. 



PenPoint 



PenPoint 
API Reference 



VOLUME I 



@ 



GO Corporation 
GO Technical Library 

Addison-Wesley Publishing Company 

Reading, Massachusetts ♦ Menlo Park, California ♦ New York 
Don Mills, Ontario ♦ Wokingham, England ♦ Amsterdam 
Bonn ♦ Sydney ♦ Singapore ♦ Tokyo ♦ Madrid ♦ San Juan 
Paris ♦ Seoul ♦ Milan ♦ Mexico City ♦ Taipei 



Many of the designations used by manufacturers and sellers to distinguish their products are claimed as 
trademarks. Where those designations appear in this book and Addison-Wesley was aware of a trademark 
claim, the designations have been printed in initial capital letters. 

The authors and publishers have taken care in preparation of this book, but make no expressed or implied 
warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for 
incidental or consequential damages in connection with or arising out of the use of the information or 
programs contained herein. 

Copyright ©1991-92 GO Corporation. All rights reserved. No part of this publication may be reproduced, 
stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photo- 
copying, recording, or otherwise, without prior written permission of the publisher. Printed in the United 
States of America. Published simultaneously in Canada. 

The following are trademarks of GO Corporation: GO, PenPoint, the PenPoint logo, the GO logo, 
ImagePoint, GOWrite, NoteTaker, TableServer, EDA, MiniNote, and MiniText. 

Words are checked against the 77,000 word Proximity/Merriam- Webster Linguibase, ©1983 Merriam 
Webster. ©1983. All rights reserved, Proximity Technology, Inc. The spelling portion of this product is 
based on spelling and thesaurus technology from Franklin Electronic publishers. All other products or 
services mentioned in this document are identified by the trademarks or service marks of their respective 
companies or organizations. 

PenTOPS Copyright © 1990-1992, Sitka Corporation. All Rights Reserved. 

Warranty Disclaimer GO CORPORATION MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT 
and Limitation of LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
Uability PURPOSE AND NONINFRINGEMENT, REGARDING PENPOINT SOFTWARE OR ANYTHING ELSE. 

GO Corporation does not warrant, guarantee, or make any representations regarding the use or the 
results of the use of the PenPoint software, other products, or documentation in terms of its correctness, 
accuracy, reliability, currentness, or otherwise. The entire risk as to the results and performance of the 
PenPoint software and documentation is assumed by you. The exclusion of implied warranties is not 
permitted by some states. The above exclusion may not apply to you. 

In no event will GO Corporation, its directors, officers, employees, or agents be liable to you for any 
consequential, incidental, or indirect damages (including damages for loss of business profits, business 
interruption, loss of business information, cost of procurement of substitute goods or technology, and the 
like) arising out of the use or inability to use the documentation or defects therein even if GO Corporation 
has been advised of the possibility of such damages, whether under theory of contract, tort (including 
negligence), products liability, or otherwise. Because some states do not allow the exclusion or limitation 
of liability for consequential or incidental damages, the above limitations may not apply to you. GO 
Corporation's total liability to you from any cause whatsoever, and regardless of the form of the action 
(whether in contract, tort [including negligence], product liability or otherwise), will be limited to $50. 

U.S. Government The PenPoint documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure 
Restricted Rights by me \j£ t Government is subject to restrictions as set forth in FAR 52.227-19 (Commercial Computer 

Software — Restricted Rights) and DFAR 252.227-7013 (c) (1) (ii) (Rights in Technical Data and Computer 
Software), as applicable. Manufacturer is GO Corporation, 919 East Hillsdale Boulevard, Suite 400, Foster 
City, CA 94404. 

ISBN 0-201-60862-6 
123456789-AL-9695949392 
First Printing, June 1 992 



PENPOINT API REFERENCE / VOL I 
PREFACE 



Preface 



The PenPoint API Reference provides reference information on the subsystems of 
the PenPoint™ operating system. Volume I describes the functions and messages 
that you use to manipulate classes and describes the fundamental classes used by 
almost all PenPoint applications. Volume II describes the supplemental classes and 
functions that provide many different capabilities to PenPoint applications. The 
text in this volume was generated from the header files in \PENPOINT\SDK\INC. 

|F Intended Audience 

The PenPoint API Reference is written for people who are developing applications 
and services for the PenPoint operating system. We assume that you are familiar 
with the C language, understand the basic concepts of object-oriented 
programming, and have read the PenPoint Application Writing Guide. 

V What's Here 

The PenPoint API Reference'^ divided into several parts, which are split across two 
volumes. Volume I contains these parts: 

♦ Part 1: Class Manager describes the PenPoint class manager classes, which 
supports object-oriented programming in PenPoint. 

♦ Part 2: PenPoint Application Framework describes the PenPoint Application 
Framework classes, which provides you the tools you use to allow your 
application to run under the notebook metaphor. 

♦ Part 3: Windows and Graphics describes ImagePoint classes and how 
applications can control the screen (or other output devices). 

♦ Part 4: UI Toolkit describes the PenPoint classes that implement many of the 
common features required by the PenPoint user interface. 

♦ Part 5: Input and Handwriting Translation describes the PenPoint input 
system classes and classes that provide programmatic access to the 
handwriting translation subsystems. 

Volume II contains these parts: 

♦ Part 6: Text Component describes the PenPoint classes that allow any 
application to provide text editing and formatting capabilities to its users. 

♦ Part 7: File System describes the PenPoint file system classes. 

♦ Part 8: System Services describes the function calls that applications can use 
to access kernel functions, such as memory allocation, timer services, process 
control, and so on. 
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♦ Part 9: Utility Classes describes a wide variety of classes that save application 
writers from implementing fundamental things such as, list manipulation, 
data transfer, and so on. 



♦ 



Part 10: Connectivity describes the classes that applications can use to access 
remote devices. 



♦ Part 11: Resources describes the classes used to read, write, and create 
PenPoint resource files. 

♦ Part 12: Installation API describes the PenPoint classes that support installing 
applications, services, fonts, dictionaries, handwriting prototypes, and so on. 

Part 13: Writing PenPoint Services, describes classes used in writing an 
installable service. 



♦ 



Other Sources of Information 

As mentioned above, the PenPoint Application Writing Guide provides a tutorial 
on writing PenPoint applications. The tutorial is illustrated with several sample 
applications. 

The PenPoint Development Tools describes how to run PenPoint on a PC, how to 
debug programs, and how to use a number of tools to enhance or debug your 
applications. This volume also contains a Master Index to the five volumes 
included in the PenPoint SDK. 

The PenPoint Architectural Reference groups the PenPoint classes into several 
functional areas and describes how to use these classes. The PenPoint Architectural 
Reference is divided into two volumes. The first volume describes the fundamental 
classes that all application developers will use; the second volume describes 
supplemental classes that application developers may, or may not, use. 

To learn how to use PenPoint, you should refer to the PenPoint user documen- 
tation. The user documentation is included with the PenPoint SDK, and is usually 
packaged with a PenPoint computer. The user documentation consists of these 
books: 

♦ Getting Started with PenPoint, a primer on how to use PenPoint 

♦ Using PenPoint, a detailed book on how to use PenPoint to perform tasks and 
procedures. 
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Type Styles in This Book 



f Type Styles in This Book 

To emphasize or distinguish particular words or text, we use different fonts. 

P^ Computerese 

We use fonts to distinguish two different forms of "computerese": 

♦ C language keywords and preprocessor directives, such as switch, 
case, #def ine, #if def , and so on. 

♦ Functions, macros, class names, message names, constants, variables, 
and structures defined by PenPoint, such as msgListAddltem, clsList, 
stsBadParam, P_LIST_NEW, and so on. 

Although all these PenPoint terms use the same font, you should note that 
PenPoint has some fixed rules on the capitalization and spelling of messages, 
functions, constants, and types. By the spelling and capitalization, you can 
quickly identify the use of a PenPoint term. 

♦ Classes begin with the letters "els"; for example, clsList. 

♦ Messages begin with the letters "msg"; for example, msgNew. 

♦ Status values begin with the letters "sts"; for example, stsOK. 

♦ Functions are mixed case with an initial upper case letter and trailing 
parentheses; for example, OSMemAvailable(). 

♦ Constants are mixed case with an initial lower case letter; for example, 
wsClipChildren. 

♦ Structures and types are all upper case (with underscores, when needed, 
to increase comprehension); for example, U32 or LIST_NEW_ONLY. 

V Placeholders 

Anything you do not have to type in exactly as printed is generally formatted in 
italics. This includes C variables, suggested filenames in dialogs, and pseudocode 
in file listings. 

i|p Other Text 

The documentation uses italics for emphasis. When a Part uses a significant term, 
it is usually emphasized the first time. If you aren't familiar with the term, you can 
look it up in the Glossary in the PenPoint Application Writing Guide or the index 
of the book. 

DOS filenames such as \\BOOT\PENPOINT\APP are in small capitals. PenPoint file 
names can be upper and lower case, such as \My DiskWPackage Design Letter. 

Book names such as PenPoint Application Writing Guide are in italics. 
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Part 1 / Class Mana 


ger 


l 


CHMGR.H 


CLSMGR.H 




3 


CHOICE.H 


DEBUG.H 




47 


CLAYOUT.H 


GO.H 




53 


CLOSEBOX.H 


MAIN.H 




61 


CMDBAR.H 


UID.H 




63 


CONTROL.H 
COUNTER.H 


Part 2 / PenPoint Application 
Framework 


77 


FIELD.H 
FONTLBOX.H 


APP.H 




79 


FRAME.H 


APPDIR.H 




111 


GRABBOX.H 


APPMGR.H 




119 


ICHOICE.H 


APPMON.H 




127 


ICON.H 


APPTAG.H 




137 


ITABLE.H 


APPWIN.H 




143 


ITOGGLE.H 


CBWIN.H 




149 


LABEL.H 


CLSPRN.H 




151 


LISTBOX.H 


EMBEDWIN.H 




157 


MANAGER.H 


EWNEW.H 




173 


MBUTTON.H 


GOTO.H 




175 


MCICON.H 


ICONWIN.H 




179 


MENU.H 


MARK.H 




183 


MFILTER.H 


PRFRAME.H 




199 


NOTE.H 


PRINT.H 




203 


OPTION.H 


PRLAYOUT.H 




213 


OPTTABLE.H 


PRMARGIN.H 




215 


PAGENUM.H 


RCAPP.H 




217 


POPUPCH.H 


VIEW.H 




219 


PROGRESS.H 


Part 3 / Windows and Graphics 


223 


SBAR.H 
SELCHMGR.H 


BITMAP.H 




225 


SFIADOW.H 


CCITT.H 




229 


STDMSG.H 


GEO.H 




233 


STRLBOX.H 


PICSEG.H 




241 


SWIN.H 


SYSFONXH 




253 


TABBAR.H 


SYSGRAF.H 




257 


TBAR.H 


TIFF.H 




287 


TBUTTON.H 


TILE.H 




293 


TKFIELD.H 


WIN.H 




295 


TKTABLE.H 


Part 4 / Ul Toolkit 




325 


TLAYOUT.H 


BORDER.H 
BUSY.H 




327 
345 


TRACK.H 
TTABLE.H 


BUTTON.H 




347 
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383 
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401 
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V Part 5 / Input and Handwriting 
Translation 



ACETATE.H 

ANIMSP.H 

GWIN.H 

HWCUSTOM.H 

HWLETTER.H 

INPUT.H 

INSERT.H 

KEY.H 

KEYBOARD.H 

KEYCAP.H 

KEYSTATE.H 

PEN.H 

SCRIBBLE.H 

SPAPER.H 

XGESTURE.H 

XLATE.H 

XLFILTER.H 

XLIST.H 

XSHAPE.H 

XTEACH.H 

XTEMPLT.H 

XTEXT.H 

XTRACT.H 

XWORD.H 
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CLSMGR.H 



The Class Manager supports object-oriented programming. 

clsObject inherits from null. 

clsObject is the root of the Object System. It defines the basic capabilities of all objects. 

clsClass inherits from clsObject. 

clsClass is the root of all classes. clsClass provides class creation capabilities. 

#ifndef CLSMGR_INCLUDED 
tdefine CLSMGR INCLUDED 



F Overview 



This file defines all the subroutines and messages that implement Object-oriented programing under 
PenPoint. The most important of these are: 

ObjectCall() and related routines, especially the Debugging Routines 

MsgHandler() and related macros 

MakeMsgO macro 

clsClass, CLASS_NEW_DEFAULTS, etc. 

clsObject, OBJECT_NEW_DEFAULTS, etc. 

msgNew, msgNewDefaults, msglnit, msgDestroy, msgFree, msgSave, msgRestore 

Look at the functions starting with ClsStsToString too. 

This is one of PenPoint's key header files. Developers should browse through this file and be familiar 
with its contents. Other key header files are go.h, app.h, and win.h. 

To fully understand what's going on here, you should read the Class Manager section of the PenPoint 
Architecture Reference. 



Guidelines 



Normally you should call your ancestor before processing a message. Possible exceptions include: 

messages that are defined by your class. Obviously, these shouldn't go to your ancestor at all. 

messages that you want to explicitly override. Depending on whether you want to override the 
message some of the time or all the time. 

msgFreeOK, msgFreeing, msgFree should use objCallAncestorAfter. 

protocols that requires the subclass to act on the message before the ancestor receives it. 
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fy Debugging Flags 

The ClsMgr debugging flag set is 'C\ Defined values are: 

000001 Show calls to ObjectCall(). 

000002 Show calls to ObjectCallAncestor(). 
000004 Show calls to ObjectSend(). 
000008 Show calls to ObjectPost(). 

000010 Show indirect calls (class messages) for traced objects. 

000020 Show object new and free calls. 

000040 Show observer related actions: add, remove, notify and post. 

000080 Show messages as they are dispatched. 

000100 Show objects as they are saved and restored. 

000200 Gather ObjectCall depth statistics. 

000400 Show objects as they are scavenged at task termination. 

000800 Enter Debugger(), if bad object is passed to ObjectCall(). 

001000 Show calls to ObjectCallAncestor() for traced objects. 

002000 Enable detailed messages from ObjectValid(). These messages are not necessarily errors if the 
client code handles stsBadObject. Because null objects are common they are not reported under 
C2000. 

004000 Enable miscellaneous error/warning messages: Bad newStruct, Message not understood, WKN 
already exists, WKN replaced (warning). 

008000 Enter the debugger after printing a warning. 

Temporary flags: 

010000 Fills the stack w/FO's before calling a method. This is useful for catching uninitialized variables. 

020000 Show calls to extended ObjectCall() and ObjectCallAncestor(). 

Implementor Flags: 

100000 Show all clsmgr statuses, legitimate errors are included. 

#ifndef GO_INCLUDED 

♦include <go.h> 
#endif 
#ifndef OSTYPES_INCLUDED 

♦include <ostypes.h> 
♦endif 
♦ifndef UID_INCLUDED 

♦include <uid.h> 
♦endif 











CLSMGR.H 


!#«■■■■, 








Object Capabilities 


Valu< 

♦define 


BS 

stsBadObject 


MakeStatus (clsObject, 


2) 




#define 


stsBadAncestor 


MakeStatus (clsObject, 


4) 




♦define 


stsBadContext 


MakeStatus (clsObject, 


6) 




#define 


stsProtectionViolation 


MakeStatus (clsObject, 


8) 




#define 


stsScopeViolation 


MakeStatus (clsObject, 


10) 


// (.asm) 


#define 


stsTaskTerminated 


MakeStatus (clsObject, 


12) 




♦define 


stsSizeLimit 


MakeStatus (clsObject, 


14) 




♦define 


stsBadPropTag 


MakeStatus (clsObject, 


16) 




♦define 


stsNewStructError 


MakeStatus (clsObject, 


18) 




♦define 


stsClassHasReferences 


MakeStatus (clsObject, 


20) 




♦define 


stsNotUnderstood 


MakeStatus (clsObject, 


22) 




♦define 


stsVetoed 


MakeStatus (clsObject, 


26) 




♦define 


stsWellKnownExists 


MakeStatus (clsObject, 


28) 




♦define 


stsBadMethodTable 


MakeStatus (clsObject, 


30) 


// (.asm) 



|F Non-Error Status Values 



stsMessagelgnored is equal to stsRequestForward for historical reasons. MakeWarning is used to force 
the entry into the symbols DB. 



♦define 


stsMessagelgnored 


MakeWarning (clsGO, 2) 




♦define 


st sAlready Added 


MakeWarning (clsObject , 


2) 


♦define 


s t s Al readyRemoved 


MakeWarning (clsObject, 


3) 


♦define 


stsSendTasklnvalid 


MakeWarning (clsObject, 


4) 


♦define 


s t sWe 1 lKnownReplaced 


MakeWarning (clsObject, 


6) 


♦define 


stsTraceOn 


MakeWarning (clsObject , 


7) 


♦define 


stsTraceOff 


MakeWarning (clsObject, 


8) 



r Object Capabilities 



♦ifndef M_I86 




// 


32 


bit 


compiler 




Enum32 (OBJ_CAPABILITY 
i 


) 


// 
// 
// 


default for: 


OBJECT 


CLASS 


i 
objCapOwner 


flagl, 








TRUE 


FALSE 


objCapFree 


flag2, 


// 








TRUE 


FALSE 


objCapSend 


flag3, 


// 








TRUE 


FALSE 


objCapObservable = 


flag4, 


// 








TRUE 


TRUE 


objCapInherit 


flag6, 


// 








n/a 


TRUE 


objCapScavenge = 


flag7, 


// 


enable 


only: 


n/a 


FALSE 


objCapCreate 


flag8, 


// 








FALSE 


FALSE 


objCapProp 


flag9, 


// 








TRUE 


TRUE 


objCapMutate 


flaglO, 


// 








TRUE 


TRUE 


objCapCall 


flagl5, 


// 








FALSE 


TRUE 


objCapCreateNotify 


= flagl6, 


// 


create 


only: 


FALSE 


FALSE 


objCapUnprotected = 


flagl7, 


// 


create 


only: 


n/a 


FALSE 


ob j CapNonSwappable 

\ ■ 


= flagl8 


// 


create 


only: 


FALSE 


FALSE 


1 1 
♦else 




// 


16 


bit 


compiler 




typedef U32 OBJ CAPABILITY; 














♦endif 
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Types Derived Directly from Base Types 



OBJECT, TAG, STATUS, etc. are 

typedef OBJECT 
typedef TAG 
typedef PJJNKNOWN 
typedef PJJNKNOWN 
typedef PJJNKNOWN 
typedef U32 
#define objWKNKey 
typedef const U32 



defined in <go.h> 

CLASS, *P_CLASS; 
MESSAGE, *P_MESSAGE; 
P_ARGS, *PP_ARGS; 
CONTEXT, *P_CONTEXT; 
P_IDATA, *PP_IDATA; 
OBJ_KEY, *P_OBJ_KEY; 
((OBJ_KEY)0) 
*P MSG, **PP MSG; 



// message table 



Constants and Types Derived from Structs 



NewArgs used to create an object. 

typedef struct OBJECTJNEW { 
U32 newStructVersion; 



OBJ_KEY 
OBJECT 

OBJ_CAP ABILITY 
CLASS 



OS HEAP ID 



U32 
U32 



key; 
uid; 

cap; 
objClass; 



heap; 



spare 1; 
spare2 ; 



} OBJECT NEW ONLY, OBJECT NEW, * P 



// Out: [msgNewDefaults] Validate msgNew 
// In: [msgNew] Valid version 
// In: [msgNew] Lock for the object 
// In: [msgNew] Well-known uid 
// Out: [msgNew] Dynamic or Well-known uid 
// In: [msgNew] Initial capabilities 
// Out: [msgNewDefaults] Set to self 
// In: [msgObjectNew] Class of instance 
// In: [msg*] Used by toolkit components 
// Out: [msgNewDefaults] Heap to use for 
// additional storage. If capCall then 
// OSProcessSharedHeap else OSProcessHeap 
// Unused (reserved) 
// Unused (reserved) 
OBJECT NEW ONLY, * P OBJECT NEW; 



New defaults fields for subclassing OBJECT. 

♦define objectNewFields OBJECT_NEW_ONLY object; 

Fields for initializing a class. 



typedef struct CLASS JJEWJDNLY { 
P_MSG pMsg; 

CLASS ancestor; 

SIZEOF size; 



// In: Can be pNull for abstract class 

// In: Ancestor to inherit behavior from 

// In: Size of instance data, can be 

// (see comment below) 

SIZEOF newArgsSize; // In: Size of XX_NEW struct, can be 

// Value limited to U16 

U32 sparel; // Unused (reserved) 

} CLASS_NEW_ONLY, * P_CLASS_NEW_ONLY; 

Limits on instance data size: 

Instance data for any class is limited to 64K bytes. Instance data for an entire objects is limited to 64K of 
protected data. Unprotected instance data is limited to 64K bytes per class but there is no limit for the 
object. 

New defaults fields for subclassing CLASS. 

♦define classNewFields objectNewFields CLASS JJEWJDNLY els; 

NewArgs used to create a class. 

typedef struct CLASS_NEW { 

classNewFields 
} CLASS NEW, * P CLASS NEW; 



CLSMGR.H 
Constants and Types Derived from Structs 

Enable/Disable capabilities 

typedef struct OBJ_CAPABILITY_SET { 

OBJ_CAPABILITY cap; // In: Capabilities to enable/disable 

OBJ_KEY key; // In: Unlocks object, e.g., objWKNKey 

} OBJ_CAPABILITY_SET, * P_OBJ_CAPABILITY_SET; 

Set/Get owner 



typedef struct OBJ_OWNER { 
OS_TASK_ID task; 

OBJECT Object; 

OBJJCEY key; 

} OBJ_OWNER, * P_OBJ_OWNER; 

Set/Get properties 

typedef struct OBJ_PROP { 
TAG propld; 

P IDATA pData; 



SIZEOF 



length; 



OBJJCEY key; 

} OBJ_PROP, * P_OBJ_PROP; 

Add/Get observers 

typedef struct OBJ_OBSERVER_POS { 
OBJECT observer; 



U16 



position; 



// In: 
// Out: 
// In: 
// In: 



// In: 

// In: 

// In: 

// In: 

// Out: 

// In: 

// In: 



// In: 
// Out: 
// In: 



} OBJ_OBSERVER_POS, * P_OBJ_OBSERVER_POS; 

Notify observers 

typedef struct OBJ_NOTIFY_OBSERVERS { 
MESSAGE msg; // In: 

P_ARGS pArgs; //In: 

SIZEOF lenSend; //In: 



[msgSetOwner] New owner 
[msgObjectOwner] Current owner 
[msgObject Owner] Source object 
[msgSet Owner] If required by caps 



[msgProp] Name of property 
[msgProp] Pointer to data 
[msgSetProp] Data to copy to prop 
[msgProp] # of bytes to copy 
[msgProp] Length of data in bytes 
[msgSetProp] # of bytes to write 
[msgSetProp] If required by cap 



[msgAddObserverAt] New observer 
[msgGet Observer] Observer at pos 
Position in observer list 



Message to send/post observers 
Args for message 
Length of Args 



} OBJ_NOTIFY_OBSERVERS, * P_OBJ_NOTIFY_OBSERVERS; 

Buffer to hold symbol string. Used with ClsStsToString, etc. 

♦define clsSymBufSize 80 

typedef char P_CLS_SYMBUF[clsSymBufSize] ; 

Array entry for OBJECT in the symbols database. 

typedef struct CLS_SYM_OBJ { 

OBJECT obj; 

P_STRING name; 

} CLS_SYM_OBJ, *P_CLS_SYM_OBJ, * *PP_CLS_SYM_OBJ; 

Array entry for message in symbols database. 

typedef struct CLS_SYM_MSG { 

MESSAGE msg; 

P_STRING name; 

} CLS_SYM_MSG, *P_CLS_SYM_MSG, * *PP_CLS_SYM_MSG; 

Array entry for STATUS in symbols database. 

typedef struct CLS_SYM_STS { 

STATUS sts; 

P_STRING name; 
} CLS SYM STS, *P CLS SYM STS, * *PP CLS SYM STS; 
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^ Types Required for msgSave and 
msgRestore 



RES ID, *P RES ID; 



Resouce IDs 
typedef TAG 
System flags for save and restore. 

Enuml 6 (RES_SAVE_RESTORE_FLAGS ) { 

resDoingCopy = flagO 
}; 
typedef struct OBJ_SAVE { 

OBJECT file; 

RES_ID res Id; 

OBJECT root; 

P_UNKNOWN pEnv; 

U16 minSysVersion; 

U16 minApp Vers ion; 

RES_SAVE_RESTORE_FLAGS sysFlags; 

U16 appFlags; 

P_UNKNOWN pFile; 

U32 spare 1; 

U32 spare2; 

} OBJ_SAVE, * P_OBJ_SAVE; 
typedef struct OBJ RESTORE { 



// Resource ID 



// Creating a copy of object 



// In: 



// In: 

// 

// 

// 

// 

// 

// 

// 



OBJECT_NEW 


object; 


// In: 


OBJECT 


file; 


// In: 


RES_ID 


resld; 


// In: 


OBJECT 


root; 


// In: 


P UNKNOWN 


pEnv; 


// In: 


U16 


sysVersion; 


// In: 


U16 


appVersion; 


// In: 


RES SAVE RESTORE 


_FLAGS sysFlags; 


// In: 


U16 


appFlags; 


// In: 


P UNKNOWN 


pFile; 


// In: 


U32 


sparel ; 


// Unu 


U32 


spare2 ; 


// Unu 


} OBJ_RESTORE, * P_ 


OBJ RESTORE; 





File to save object to 
Resource Id of root-level object 
In: Uid of root-level object 
In : Environment to be saved 
In/Out: Min acceptable system version 
In/Out: Min acceptable app version 
In: System flags 
In: App flags 
In: StdIO FILE* bound to file above 

// Unused (reserved) 

// Unused (reserved) 



New defaults for restored object 

File to restore object from 

Resource Id of root-level object 

Uid of root-level object 

Saved environment 

Sys version number of filed data 

App version number of filed data 

System flags 

App flags 

StdIO FILE* bound to file above 



^Method Definition Macros 

Definition of a pointer to a method. 

#ifdef HIGHC 



Function Prototype 
Function Prototype 



typedef CDECL STATUS (* P_MSG_HANDLER) ( 
#else 

typedef STATUS (CDECL * P_MSG_HANDLER) ( 
#endif 

MESSAGE msg, 

OBJECT self, 

P_ARGS pArgs, 

CONTEXT ctx, 

P_IDATA pData 

); 

Definition of a method. 

tdefine MSG_HANDLER STATUS CDECL 

Shorthand used to declare a method. 

tdefine MsgHandler(fn) MSG HANDLER MsgHandlerPrimitive(fn, P ARGS, P IDATA) 
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Shorthand used to declare a method with pArgs cast to appropriate type. Note: pArgsType must be a <5 

pointer type. 

♦define MsgHandlerArgType(fn, pArgsType) \ 

MSGJHANDLER MsgHandlerPrimitive (fn, pArgsType, P_IDATA) 

Shorthand used to declare a method with casts for pArgs and instance data. Note: pArgsType and 
plnstData must be pointer types. 

♦define MsgHandlerWithTypes (fn, pArgsType, plnstData) \ 

MSG_HANDLER MsgHandlerPrimitive (fn, pArgsType, plnstData) 

Shorthand used to declare a method. Very fast and very dangerous. DS is NOT loaded. Don't use 
strings, local functions, statics, etc. 

♦define MsgHandlerRingCHelper(fn) \ 

STATUS CDECL MsgHandlerPrimitive (fn, P_ARGS, P_IDATA) 

Shorthand used to declare a method. 

♦define MsgHandlerPrimitive (fn, pArgsType, plnstData) fn(\ 
const MESSAGE msg, \ 
const OBJECT self, \ 
const pArgsType pArgs, \ 
const CONTEXT ctx, \ 
const plnstData pData) 

Cast pData to the appropriate type. 

tdefine IDataPtr(pData, type) ( (type*)pData) 

Copy protected instance data block into local storage. 

♦define IDataDeref (pData, type) (*(type*)pData) 

Shorthand used to ignored any unused parameters in a method. 

♦define MsgHandlerParametersNoWarning \ 

Unused(msg) ; Unused(self) ; Unused (pArgs) ; Unused(ctx); Unused(pData) 

Message Macros 

message numbers are between and 254, inclusive. Message number 255 

♦define MakeMsg(wkn,msg) MakeTag(wkn,msg) 

Extract the message portion of a message. 

♦define MsgNum(msg) TagNum(msg) 

The WKNValue unique represents a class. 

♦define ClsNum(msg) WKNValue (msg) 

Messages defined with MsgNoError() will not generate a msgNotUnderstood error if they reach 
clsObject. Instead, stsMessagelgnored is returned. 

♦define MsgNoError(msg) ( (msg) ImsgNoErrorFlag) 

♦define msgNoErrorFlag (1L«21) 

Messages that are handled as class messages have this flag added to the message value. 

♦define msgClassMessageFlag (1L«22) 

Compare two messages for equality. 

♦define MsgEqual(ml,m2) (ml==m2) 
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|F Object Scope Macros 

(Well-Known and Dynamic) 

♦define Ob jectlsDynamic (o) ( (U32) (o) &ob jDynamicFlag) 

tdefine ObjectlsWellKnown (o) (! Ob jectlsDynamic (o) ) 

#define ObjectlsWKN(o) ObjectlsWellKnown (o) 

tdefine ObjectlsGlobal(o) (ObjectlsDynamic(o) I |ObjectIsGlobalWKN(o) ) 

tdefine Ob jectlsLocal (o) ( ! Ob jectlsGlobal (o) ) 

tdefine ObjectlsGlobalWKN(o) (ObjectlsWKN(o) && WKNScope(o)==wknGlobal) 

tdefine ObjectlsProcessGlobalWKN(o) \ 

(ObjectlsWKN(o) && WKNScope(o)==wknProcessGlobal) 
tdefine ObjectlsPrivateWKN(o) (ObjectlsWKN(o) && WKNScope(o)==wknPrivate) 

All dynamic objects have this bit set in their UID. 

tdefine objDynamicFlag 0x800000 

P Messages 

// Recycle: 

// Next available: 120 



msgNull 

Not a real message, just a place holder. 

Takes pNull, returns STATUS. 

tdefine msgNull MakeMsg(objNull, 0) 



msgNewDefaults 

Initializes new struct to default values. 

Takes new struct for object being created, returns STATUS. Category: class message. 

tdefine msgNewDefaults MakeMsg(clsObject, 2) 

msgNew 

Creates an object and sends msglnit to the new object. 

Takes new struct for object being created, returns STATUS. Category: class message. 

tdefine msgNew MakeMsg(clsObject, 4) 

Comments Developers normally send this message to class objects in order to create instances but they do NOT 

write code that handles msgNew. The class manager does some processing on msgNew internally and 
finally sends msglnit, which developers DO need to handle. 

Return Value stsNewStructError The new struct was not properly initialized, it was used more than once, or it was 

overwritten. 

stsBadParam Format of well-known UID was invalid. 

stsWellKnownExists Well-known UID has already been created with a different key. 

stsOSOutOfMem Too many objects have been created or system memory is exhausted. 

stsProtectionViolation (clsClass) objCapInherit is disabled. 

stsSizeLimit (clsClass) More than the maximum amount of instance data has been requested. 

stsBadAncestor (clsClass) Ancestor is not a class. 
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msgNewWithDefaults 

Creates an object with default values. 

Takes new struct for object being created, returns STATUS. Category: class message. 

♦define msgNewWithDefaults MakeMsg(clsObject, 5) 

Comments Self sends msgNewDefaults followed by msgNew. Useful when changes to the new struct are NOT 

required. 

msglnit 

Sent to the object immediately after it is created. 

Takes new struct for object being created, returns STATUS. 

♦define msglnit MakeMsg(clsObject, 6) 

Comments When msglnit reach clsObject the capabilities and the key in the newArgs are set for the object. This 

means that, unlike most messages, developers must call their ancestor AFTER processing this one. 



Comments 



msgCreated 

Sent to the object after it is fully created, i.e., after msglnit. 
Takes new struct for object being created, returns STATUS, 
♦define msgCreated MsgNoError (MakeMsg (clsObject, 46)) 
This message is only sent if objCapCreateNotify is enabled. 



msgDestroy 

Destroys the object. 

Takes OBJ.KEY, returns STATUS. 

♦define msgDestroy MakeMsg (clsObject, 28) 

Comments When msgDestroy is sent to the object, clsObject sends msgFreeOK, msgFreeing and msgFree to self. 

msgFreePending is sent to the observers. Only clsObject should handle msgDestroy. (That is, like 
msgNew, developers send msgDestroy but never handle it.) 

Return Yoloe stsProtectionViolation objCapFree is disabled and the key does not open the object. 

stsClassHasReferences (clsClass) Instances of the class object still exists. Only returned when the 
object being destroyed is a class. 



msgFreeOK 

Sent as the first of three messages to destroy the object. 

Takes OBJ_KEY, returns STATUS. 

♦define msgFreeOK MsgNoError (MakeMsg (clsObject, 14)) 

Comments There is no point in handling this message unless you have some reason to refuse to be freed, in which 

case return stsVetoed. Note that if the process that owns the object or the class of the object is destroyed, 
the object will be destroyed too, regardless of what it does with msgFreeOK. This is mainly useful for 
immortal system objects. 

See Also msgDestroy 
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Return Value 



stsClassHasReferences (clsClass) Instances of the class object still exists. Only returned when the 
object being destroyed is a class. 

msgFreeing 

Sent as the second of three messages to destroy the object. 

Takes OBJJKEY, returns STATUS. 

♦define msgFreeing MsgNoError(MakeMsg(clsObject, 90)) 

Comments Most developers never handle this message either. If an object is part of a tangled web of other objects, 

all of which are supposed to be freed whenver any of them is freed, it's possible to get a loop where two 
objects respond to msgFree by trying to free each other. The first object that receives msgFreeing should 
extract itself from any other object that might try to free it. When it receives msgFree, it can then safely 
send msgDestroy to those other objects. 

See Als© msgDestroy 



Comments 



See Msq 



Comments 
See Also 



msgFree 

Sent as the last of three messages to destroy the object. 

Takes OBJ_KEY, returns STATUS. 

tdefine msgFree MakeMsg(clsObject, 8) 

msgFree must succeed and error status should never be returned. Any validation should be done during 
msgFreeOK. (Like msglnit, developers handle this message but never send it.) 

msgDestroy 



msgFreePending 

Sent to observers immediately before the object is freed. 

Takes OBJECT, returns STATUS. Category: observer notification. 

♦define msgFreePending MsgNoError(MakeMsg(clsObject, 70)) 

If an observer cares about the final state of the object, this is the last opportunity to send it a message. 

msgDestroy 



msgRestorelnstance 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

#define msgRestorelnstance MakeMsg(clsObject, 80) 



Message 


typedef struct OBJ RESTORE { 




Arguments 


OBJECT NEW object; 


// In: 




OBJECT file; 


// In: 




RES ID resld; 


// In: 




OBJECT root ; 


// In: 




P UNKNOWN pEnv; 


// In: 




U16 sysVersion; 


// In: 




U16 appVersion; 


// In: 




RES SAVE RESTORE FLAGS sysFlags; 


// In: 




U16 appFlags; 


// In: 




P UNKNOWN pFile; 


// In: 




U32 spare 1; 


// Unu 




U32 spare2; 


// Unu 




} OBJ RESTORE, * P OBJ RESTORE; 





New defaults for restored object 

File to restore object from 

Resource Id of root-level object 

Uid of root-level object 

Saved environment 

Sys version number of filed data 

App version number of filed data 

System flags 

App flags 

StdIO FILE* bound to file above 



Comments 



Return Value 
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Creates an instance of the class and sends the new object msgRestore. If the new object is a class, 
msgRestoreMsgTable is sent after msgRestore. 

stsRequestNotSupported Instances of clsClass cannot be restored. 



Message 
Arguments 



Commer 



Comments 



Arguments 



msgRestore 

Creates and restores an object from an object file. 
Takes P_OBJ_RESTORE, returns STATUS. 
#define msgRestore MakeMsg(clsObject, 10) 



typedef struct OBJ 


RESTORE { 




OBJECT NEW 


object; 


// In: 


OBJECT 


file; 


// In: 


RES ID 


resld; 


// In: 


OBJECT 


root; 


// In: 


P UNKNOWN 


pEnv; 


// In: 


U16 


sysVersion; 


// In: 


U16 


appVersion; 


// In: 


RES SAVE RESTORE 


FLAGS sysFlags; 


// In: 


U16 


appFlags; 


// In: 


P UNKNOWN 


pFile; 


// In: 


U32 


spare 1; 


// Unu 


U32 


spare2 ; 


// Unu 


} OBJ RESTORE, * P 


OBJ RESTORE; 





New defaults for restored object 

File to restore object from 

Resource Id of root-level object 

Uid of root-level object 

Saved environment 

Sys version number of filed data 

App version number of filed data 

System flags 

App flags 

StdIO FILE* bound to file above 



After a new object has been created with msgRestorelnstance it is sent msgRestore. The object reads its 
instance data from the object file. 



msgRestoreMsgTable 

Returns the message table for the class. 

Takes PP_MSG, returns STATUS. 

Idefine msgRestoreMsgTable MakeMsg(clsObject, 116) 

Because the address of a message table is dynamic the ancestor of the class must provide the message 
table address when the class is restored. The ancestor can store extra information needed to find the 
message table in the instance data or as a saved property. 



msgSave 

Causes the object to file itself in an object file. 
Takes P_OBJ_SAVE, returns STATUS. 
tdefine msgSave MakeMsg(clsObject, 12) 



typedef struct OBJ_SAVE { 

OBJECT file; 

RES_ID resld; 

OBJECT root; 

PJJNKNOWN pEnv; 

U16 minSysVersion; 

U16" minAppVersion; 

RES_SAVE_RESTORE_FLAGS sysFlags; 

U16 appFlags; 

P_UNKNOWN pFile; 

U32 spare 1; 

U32 spare2; 

} OBJ SAVE, * P OBJ SAVE; 



// In: 



// In: 
// In: 
// In: 



File to save object to 
Resource Id of root -level object 
Uid of root-level object 
Environment to be saved 

// In/Out: Min acceptable system version 

// In/Out: Min acceptable app version 

// In: System flags 

// In: App flags 

// In: StdIO FILE* bound to file above 

// Unused (reserved) 

// Unused (reserved) 



Comments 



clsObject files the capabilities of the object and any property that has tag flagl set. For example: 
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#define MY_PROP MakeTagWithFlags (clsFoo,tagNum, 1) 
Return Value stsRequestNotSupported (clsCkss) Classes not do file. 



msgCopy 

Passes back a copy of the object. 

Takes P_OBJ_COPY, returns STATUS. 

♦define msgCopy MakeMsg(clsObject, 54) 

Arguments typedef struct OBJ_COPY { 

OBJECT requestor; // In: Object to receive msgCopyRestore 

OBJECT object; // Out: UID of copied object 

U32 reserved[4]; // Reserved. 

} OBJ_COPY, * P_OBJ_COPY; 

Comments This message will pass back a copy of the object receiving the message. This object will be created by 

opening a temporary resource file, sending msgSave to the object, and then sending msgCopyRestore to 
the passed in requestor object. It will then close and destroy the temporary file. Note that the requestor 
object could be in a different task from the object receiving this message. In this situation, the copy of 
the object will exist in new task. 

Return ¥csloe stsFailed Could not open temporary resource file. 

See Ak© msgCopyRestore 

msgCopyRestore 

Restores the passed in object. 

Takes P_OBJ_COPY_RESTORE, returns STATUS. 

tdefine msgCopyRestore MakeMsg(clsObject, 56) 
// This struct is copied from fs.h 

Arguments typedef struct OBJ_FS_LOCATOR { 

OBJECT uid; 

P_STRING pPath; 

} OBJ_FS_LOCAT0R; 

typedef struct OBJ_COPY_RESTORE { 

OBJ_FS_LOCATOR locator; // In: File locator that the object is in 
RES_ID resld; //In: Resource id of filed object 
OBJECT object; // Out: Uid of object to return 
U32 reserved[4]; // Reserved. 

} OBJ_COPY_RESTORE, * P_OBJ_COPY_RESTORE; 

Comments This message is sent to the object with an object resource Id, and a file locator (a resource file). This will 

result in msgRestore being sent to the appropriate object to read in the resource object. Sent to the 
requestor object when performing a msgCopy. 

See Also msgCopy 



msgDump 

Causes each ancestor to print interesting debugging information. 

Takes S32, returns STATUS. 

tdefine msgDump MakeMsg(clsObject, 52) 

Comments Each class should implement a msgHandler for msgDump. The msgHandler should print out 

interesting information for the object. 
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The parameter to msgDump is used to determine how much information to print. *S 

Suggested values for pArgs: 

Implemented choice. Print whatever information is most useful. 

1 Terse. One line only. 

-1 Terse including embedded objects. One line of information plus one line for each embedded object, 
e.g., a menu would display information about each menu item. 

maxS32 Verbose. All possible information about the object. 

minS32 Verbose including embedded objects. The maximum amount of information. 

other All other values are implementation dependent. 

If the value of the parameter is in between two defined values the action should be based on the smaller 
value. 

Suggested format: 

"msgDump (yourClassName) : yourDebugginglnformation" 

clsObject defines pArgs as: 

The object's capabilities and internal address. 

1 Same as 0. 

2 Same as 1 plus owner, number of observers, number of properties, the size of instance data and size 
of property list. maxS32: Same as 2 plus hex dump of instance data. 

-1 Same as plus msgDump to observers. ([Not implemented]) 

-2 Same as -1 plus owner, number of observers, number of properties, the size of instance data. ([Not 
implemented]) 

minS32 Same as -2 plus hex dump of instance data. ([Not implemented]) 

clsClass defines pArgs as: 

The class capabilities, size of data for instances, the number of instances and subclasses of the class. 

1 Same as 0. 

2 Same as 1 plus ancestor and newArgs size. 
maxS32 Same as 2. ([Not implemented]) 

msgException 

Sent to observers of theProcess, an object within each process, when an exception occurs within that 
process. 

Takes P_OBJ_EXCEPTION, returns STATUS. Category: observer notification. 

tdefine msgException MsgNoError (MakeMsg (clsObject, 100)) 

Arguments typedef Struct 0BJ_EXCEPTI0N { 

OS_TASK_ERROR errorCode; //In: Type of exception 

0S_TASK_ID task; // In: Task that received the exception 

U32 spare; // Unused (reserved) 

} 0BJ_EXCEPTI0N, *P_0BJ_EXCEPTI0N; 

Comments If a subtask is being terminated only objects owned by the subtask are notified. 
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msgTaskTerminated 

Sent to observers of theProcess, an object within each process, after the task is terminated. 

Takes P_OBJ_EXCEPTION, returns STATUS. Category: observer notification. 

tdefine msgTaskTerminated MsgNoError(MakeMsg(clsObject, 112)) 

Message typedef struct OBJ_EXCEPTION { 

Arguments OS_TASK_ERROR errorCode; // In: Type of exception 

OS_TASK_ID task; // In: Task that received the exception 

U32 spare; // Unused (reserved) 

} OBJ_EXCEPTION, *P_OBJ_EXCEPTION; 

msgScavenge 

Sent to the object when a class has objCapScavenge set and the object's task is being terminated by 
request or because of an error. 

Takes OS__TASK_ERROR, returns STATUS. Category: descendant responsibility. 
#define msgScavenge MsgNoError(MakeMsg(clsObject, 102)) 

This message will only be executed by class that set objCapScavenge. Do not pass this message to your 
ancestor. 

msgScavenged 

Sent to the observers AFTER the object has been scavenged. 

Takes OS_TASK_ERROR, returns STATUS. Category: observer notification. 

tdefine msgScavenged MsgNoError(MakeMsg(clsObject, 104)) 



msgFreeSubTask 

Sent to theProcess to free a subtask. 

Takes P_SUBTASK_FREE, returns STATUS. 

tdefine msgFreeSubTask MsgNoError(MakeMsg(clsObject, 104)) 

l.rgomenfs typedef struct OBJ_SUBTASK_FREE { 

OS_TASK_ID task; // In: Task to be terminated 

0S_TASK_ERR0R exitCode; // In: Exit code for task termination 

} OBJ_SUBTASK_FREE, * P_0B J_SUBTASK_FREE ; 

:0m«T»etits Useful for delayed termination when message is posted to theProcess. 

latum 'Value stsOSInvalidOperationForTask Task was not a subtask of this process. 

msgHeap 

Returns the preferred heap to use when allocating storage for this object. 
Takes P_OS_HEAP_ID, returns STATUS, 
tdefine msgHeap MakeMsg(clsObject, 96) 
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Message 
Arguments 



Comments 



Return Value 



msgCan 

Checks the object's capabilities. 

Takes OBJ_CAPABILITY, returns STATUS. 

tdefine msgCan MakeMsg(clsObject, 36) 



Enum32 (OBJ_CAPABILITY 
i 


> 


// 
// 
// 


default for: 


OBJECT 


CLASS 


t 
objCapOwner 


flagl, 






TRUE 


FALSE 


objCapFree 


flag2, 


// 






TRUE 


FALSE 


objCapSend 


flag3, 


// 






TRUE 


FALSE 


objCapObservable = 


flag4, 


// 






TRUE 


TRUE 


objCapInherit = 


flag6, 


// 






n/a 


TRUE 


objCapScavenge 


flag7, 


// 


enable 


only : 


n/a 


FALSE 


objCapCreate 


flag8, 


// 






FALSE 


FALSE 


objCapProp = 


flag9, 


// 






TRUE 


TRUE 


objCapMutate 


flaglO, 


// 






TRUE 


TRUE 


objCapCall 


flagl5, 


// 






FALSE 


TRUE 


objCapCreateNotify = 


= flagl6, 


// 


create 


only -. 


FALSE 


FALSE 


objCapUnprotected = 


flagl7, 


// 


create 


only: 


n/a 


FALSE 


objCapNonSwappable = 


= flagl8 


// 


create 


only: 


FALSE 


FALSE 



}; 



If the capabilities in the parameter are all enabled, msgCan returns stsOK otherwise 
stsProtectionViolation is returned. 

stsProtectionViolation Capability disabled. 



msgDisable 

Disables some or all of the object's capabilities. 
Takes P_OBJ_CAPABILITY_SET, returns STATUS. 
#define msgDisable MakeMsg(clsObject, 16) 

typedef struct OBJ_CAPABILITY_SET { 

OBJ_CAPABILITY cap; // In: Capabilities to enable/disable 

OBJ_KEY key; // In: Unlocks object, e.g., objWKNKey 

} OBJ_CAPABILITY_SET, * P_OBJ_CAPABILITY_SET; 

stsProtectionViolation Key does not open the object. 



Message 
Arguments 



Return Value 



flessage 
Arguments 



Return ¥alue 



msgEnable 



Enables some or all of the object's capabilities. 
Takes P_OBJ_CAPABILITY_SET, returns STATUS. 
#define msgEnable MakeMsg(clsObject, 18) 

typedef struct OBJ_CAPABILITY_SET { 

OBJ_CAPABILITY cap; // In: Capabilities to enable/disable 

OBJ_KEY key; // In: Unlocks object, e.g., objWKNKey 

} OBJ_CAPABILITY_SET, * P_OBJ_CAPABILITY_SET; 

stsProtectionViolation Key does not open the object. 
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msglsA 

Tests if the object's class inherits from the class. 
Takes CLASS, returns STATUS. 
fdefine msglsA MakeMsg(clsObject, 30) 
Return Value stsOK Class is an ancestor of the object's class. 

stsBadAncestor Class is not an ancestor of the object's class. 



msgAncestorlsA 

Tests if self inherits from the class. 

Takes CLASS, returns STATUS. 

♦define msgAncestorlsA MakeMsg(clsObject, 32) 

Comments This is a clsClass message and can only be sent to a class. Consider using msglsA if the object is not a 

class. 

Return Value stsOK Class parameter is an ancestor. 

stsBadObject Class parameter is not an object. 

stsBadAncestor Class parameter is not an ancestor. 



msgClass 

Passes back the class of the object. 

Takes P_CLASS, returns STATUS. 

♦define msgClass MakeMsg(clsObject, 34) 



msgAncestor 

Passes back the ancestor of the class. 

Takes P_CLASS, returns STATUS. 

♦define msgAncestor MakeMsg(clsObject, 20) 

Commerts This is a clsClass message and can only be sent to a class. Consider using msgClass if the object is not a 

class. 

msgSetLock 

Sets or changes the key of the object. 

Takes OBJ_LOCK_SET, returns STATUS. 

♦define msgSetLock MakeMsg(clsObject, 106) 

Arguments typedef struct OBJ_LOCK_SET { 

OBJ_KEY oldKey; // In: Required to set lock 

0BJ_KEY newKey; // In: New key, if successful 

} OBJ_LOCK_SET, * P_0BJ_L0CK_SET; 

Return Value stsProtectionViolation Old key does not open the object. 
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Return Value 



msgUnlocks 

Tests if a key will unlock the object. 

Takes OBJ_KEY, returns STATUS. 

#define msgUnlocks MakeMsg(clsObject, 38) 

stsProtectionViolation Key does not open the object. 



Return Valu® 



msgDuplicateLock 

Locks the pArgs object with the same key as object. 
Takes OBJECT, returns STATUS. 

#define msgDuplicateLock MakeMsg(clsObject, 40) 
stsBadObject Parameter is not an object. 



Return Value 



msgVersion 

Returns the version of the object. 

Takes pNull, returns STATUS. 

#define msgVersion MakeMsg(clsObject, 82) 

stsScopeViolation Object was dynamic, request is nonsense. 



Comments 



msgNewArgsSize 

Returns the size of the new struct required to create an instance of this class. 

Takes pNull, returns STATUS. 

tdefine msgNewArgsSize MakeMsg(clsObject ; 92) 

This is a clsClass message and can only be sent to a class. 



msgOwner 

Passes back the task that owns this object. 
Takes P_OS_TASK_ID, returns STATUS. 
♦define msgOwner MakeMsg(clsObject, 22) 



Message 
Arguments 



msgSetOwner 

Changes the owner task. 

Takes P_OBJ_OWNER, returns STATUS. 

#define msgSetOwner MakeMsg(clsObject, 24) 



typedef struct OBJ_OWNER { 
0S_TASK_ID task; 

OBJECT object; 

OBJ_KEY key; 

} OBJ OWNER, * P OBJ OWNER; 



// In: [msgSetOwner] New owner 

// Out: [msgObjectOwner] Current owner 

// In: [msgObjectOwner] Source object 

// In: [msgSetOwner] If required by caps 



tetursi Value 



stsProtectionViolation Key does not open the object. 
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msgProp 

Passes back the value of a property for the object. 

Takes P_OBJ_PROP, returns STATUS. 

tdefine msgProp MakeMsg(clsObject, 108) 

typedef struct 0BJ_PR0P { 

TAG propld; // In: [msgProp] Name of property 

P_IDATA pData; // In: [msgProp] Pointer to data 

// In: [msgSetProp] Data to copy to prop 

SIZEOF length; // In: [msgProp] # of bytes to copy 

// Out: [msgProp] Length of data in bytes 

// In: [msgSetProp] # of bytes to write 

0BJ_KEY key; // In: [msgSetProp] If required by cap 

} 0BJ_PR0P, * P_0BJ_PR0P; 

stsBadPropTag Tag value was not in the proper range. 

msgSetProp 

Sets a property on the object. 

Takes P_OBJ_PROP, returns STATUS. 

♦define msgSetProp MakeMsg (clsObject, 110) 

;e$s0ge typedef struct 0BJ_PR0P { 

rgumertts TAG propld; // In: [msgProp] Name of property 

P_IDATA pData; // In: [msgProp] Pointer to data 

// In: [msgSetProp] Data to copy to prop 

SIZEOF length; // In: [msgProp] # of bytes to copy 

// Out: [msgProp] Length of data in bytes 

// In: [msgSetProp] # of bytes to write 

0BJ_KEY key; // In: [msgSetProp] If required by cap 

} 0BJ_PR0P, * P_0BJ_PR0P; 

ymmenu clsObject files any property that has tag flag 1 turned on. For example: 

tdefine MY_PR0P MakeTagWithFlags(clsFoo,tagNum, 1) 

»fyra ¥aioe stsBadPropTag Tag value was not in the proper range. 

stsProtectionViolation Key does not open the object. 

r msgObjectXXX 

These msgObjectXXX messages can be used with ObjectCall() to get information about all objects, 
regardless of their task. Functionally they are equivalent to msgXXX, when applicable. 

msgObjectlsA 

Using the object and the class in the pArgs. Tests if the object's class inherits from the class. 

Takes P_OBJ_IS_A, returns STATUS. 

tdefine msgObjectlsA MakeMsg (clsObject, 84) 

rgoments typedef struct 0BJ_IS_A { 

OBJECT object; // In: Source object 

CLASS objClass; // In: Ancestor of source object's class 

} 0BJ_IS_A, * P_0BJ_IS_A; 

sforn Value stsBadObject Parameter is not an object. 

stsBadAncestor Class is not an ancestor of the object's class. 
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Arguments 

Comments 
Return Value 



msgOb j ectAncestorlsA 



Tests if the descendant class inherits from the ancestor. 

Takes P_OBJ_ANCESTOR_IS_A, returns STATUS. 

#define msgObjectAncestorlsA MakeMsg(clsObject, 86) 

typedef struct OBJ_ANCESTOR_IS_A { 

CLASS descendant; // In: Source class (always a class) 

CLASS ancestor; // In: Ancestor of the descendant 

} OBJ_ANCESTOR_IS_A, * P_OBJ_ANCESTOR_IS_A; 

This is a clsClass message and can only be sent to a class. 
stsBadObject One of the parameters is not a class. 
stsBadAncestor Ancestor parameter is not an ancestor. 



Arguments 



Return Valoe 



msgObjectClass 

Passes back the class for the object in pArgs. 

Takes P_OBJ_CLASS, returns STATUS. 

tdefine msgObjectClass MakeMsg(clsObject, 88) 



typedef struct OBJ_CLASS { 
OBJECT object; 

CLASS objClass; 

} OBJ CLASS, * P OBJ CLASS; 



// In: Source object 

// Out: Class of source object 



stsBadObject Object or class parameters are not objects. 



Message 
Arguments 



Return Volue 



msgObjectOwner 

Passes back the owning task for the object in pArgs. 

Takes P_OBJ_OWNER, returns STATUS. 

#define msgObjectOwner MakeMsg(clsObject, 26) 



typedef struct OBJ_OWNER { 
OS_TASK_ID task; 

OBJECT object; 

OBJ_KEY key; 

} OBJ OWNER, * P OBJ OWNER; 



// In: [msgSetOwner] New owner 

// Out: [msgObjectOwner] Current owner 

// In: [msgObjectOwner] Source object 

// In: [msgSetOwner] If required by caps 



stsBadObject Parameter is not an object. 



Return Volue 



msgObjectValid 

Tests that the object in pArgs exists. 

Takes OBJECT, returns STATUS. 

#define msgObjectValid MakeMsg(clsObject, 42) 

stsBadObject Parameter is not an object. 

stsBadAncestor Invalid ancestor. 
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msgObjectVersion 

Returns the version of the object in pArgs. 
Takes OBJECT, returns STATUS. 

#define msgObjectVersion MakeMsg(clsObject, 44) 
Return Value stsBadObject Parameter is not an object. 

stsScopeViolation Parameter was dynamic, request is nonsense. 



msgObjectNew 

Creates a new object in the same context as the object that receives this message. 

Takes newArgs, returns STATUS. 

#define msgObjectNew MakeMsg(clsObject, 98) 

stsProtectionViolation objCapCreate is disabled. 

stsScopeViolation Must be executed in the owner task of the receiving object. 

msgTrace 

Turn tracing on for classes and objects. Return value is stsTraceOn if tracing was on and stsTraceOff if 
tracing was off. 

Takes TAG, returns STATUS. 

tdefine msgTrace MakeMsg(clsObject, 48) 
tdefine objTraceOn (P_ARGS)stsTraceOn 
tdefine objTraceOff (P_ARGS)stsTraceOff 

mts When tracing is turned on for the object, every ObjectCall() to the object causes a 3-line message to be 

printed. The format of the output is: 

C> Trace ObjectCall: @ cls="ancestor name" task="task" 

O object=" object name" depth="D" 

C> msg="message name", pArgs="address", pData=" address" 

On return from the ObjectCall () a 2-line message is printed. The format of the output is: 

C> Trace ObjectCall: returns=" status value" task="task" 

C> ob ject=" object name" depth="D/C" 

where task is the task id in hex, depth is the number of recursive dispatch loops. All names are printed 
symbolically when symbols are available. 

ObjectCallAncestor() calls are traced for objects if tracing is on for the object and the debug flag 
/DClOOOisset. 

When tracing is turned on for a class, the class is traced as an object. In addition, all 
ObjectCallAncestorQ calls that pass through the class are traced. 
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Arguments 



Comments 



Return Value 



msgMutate 

Changes the ancestor of the object to be the newAncestor class. 
Takes P_OBJ_MUTATE, returns STATUS. 

♦define msgMutate MakeMsg(clsObject, 46) 



typedef struct OBJ_MUTATE { 
CLASS newClass; 

OBJ_KEY key; 

} OBJ MUTATE, * P OBJ MUTATE; 



// In: Object's new class 
// In: If required by caps 



The total size of the instance data for the new and old ancestors must be equal, this is the sum for all the 
ancestors up to clsObject. This message is NOT intended for general use. Use it when the behavior of 
an existing object needs to be overridden. 

stsBadAncestor The newAncestor class is not a valid class. 

stsSizeLimit The sizes of new and old instance data don't match. 



teturn Volue 



irquments 



msgAddObserver 

Adds an observer to the end of the object's observer list. 

Takes OBJECT, returns STATUS. 

#define msgAddObserver MakeMsg (clsObject, 58) 

stsBadObject Parameter is not an object. 

stsProtectionViolation objCapObservable is disabled. 

stsScopeViolation Observer is local and has a different owner than the observed object or the observed 
object is callable. 

stsAlreadyAdded The same observer has been added twice. This is only a warning, the observers are ref 
counted. Two adds require two removes. 



msgAddObserverAt 

Adds an observer at the specified position in the observer list. 

Takes P_OBJ_OBSERVER_POS, returns STATUS. 

♦define msgAddObserverAt MakeMsg (clsObject, 78) 



typedef struct OBJ_OBSERVER_POS { 
OBJECT observer; 



// In: [msgAddObserverAt] New observer 
// Out: [msgGet Observer] Observer at pos 
Position in observer list 



U16 position; // In 

} OBJ_OBSERVER_POS, * P_OB J_OBSERVER_POS ; 

stsBadObject Parameter is not an object. 

stsProtectionViolation objCapObservable is disabled. 

stsScopeViolation Observer is local and has a different owner than the observed object or the observed 
object is callable. 

stsAlreadyAdded The same observer has been added twice. This is only a warning, the observers are ref 
counted. Two adds require two removes. 
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-ommertts 
tetom Valt 



msgRemoveObserver 

Removes an observer from the object's observer list. 
Takes OBJECT, returns STATUS. 

tdefine msgRemoveObserver MakeMsg(clsObject, 60) 
msgRemoved is sent to the observer after it is removed. 
stsProtectionViolation objCapObservable disabled. 
stsAlreadyRemoved Observer was not on the list. 



msgNotifyObservers 

Sends a message to the observers. 

Takes P_OBJ_NOTIFY_OBSERVERS, returns STATUS. 
tdefine msgNotifyObservers MakeMsg(clsObject, 62) 

Messoge typedef struct OBJ_NOTIFY_OBSERVERS { 

Arguments MESSAGE msg; // In: Message to send/post observers 

P_ARGS pArgs; // In: Args for message 

SIZEOF lenSend; // In: Length of Args 

} OBJ_NOTIFY_OBSERVERS, * P_OBJ_NOTIFY_OBSERVERS; 

Comments Any observer that returns stsBadObject is removed from the observer list. 



msgPostObservers 

Posts a message to the observers. 

Takes P_OBJ_NOTIFY_OBSERVERS, returns STATUS. 

♦define msgPostObservers MakeMsg(clsObject, 94) 

typedef struct OBJ_NOTIFY_OBSERVERS { 

MESSAGE msg; // In: Message to send/post observers 

P_ARGS pArgs; // In: Args for message 

SIZEOF lenSend; // In: Length of Args 

} OBJ_NOTIFY_OBSERVERS, * P_OBJ_NOTIFY_OBSERVERS; 

Any observer that returns stsBadObject is removed from the observer list. 



Me$$0€pe 
Arguments 



Comments 



Arguments 



msgEnumObservers 

Passes back the observer list. 

Takes P_OBJ_ENUM_OBSERVERS, returns STATUS. 

tdefine msgEnumObservers MakeMsg(clsObject, 64) 



typedef struct OBJ_ENUM_OBSERVERS { 



U16 


max, 


// In: 




count ; 


// In: 

// 

// Out 


P_OBJECT 


pObservers; 


// In: 
// Out 
// 


U16 


next; 


// In: 
// Out 



Size of pObservers [] 

# to pass back in pObservers [] . 

If count > max memory may be allocated 

# of valid entries in pObservers [] 
ptr to array 

If memory was allocated 
client should free the memory 
Set to for the first call 
Next available entry 



} OBJ ENUM OBSERVERS, * P OBJ ENUM OBSERVERS; 



Return Value stsEndOfData The size of the array is greater than or equal to the number of observer. 
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Message 
Arguments 



Comments 



msgGetObserver 

Passes back the observer at the specified position in the observer list. 
Takes P_OBJ_OBSERVER_POS, returns STATUS. 
♦define msgGetObserver MakeMsg (clsObject, 74) 
typedef struct OBJ_OBSERVER_POS { 



OBJECT 



observer; 



// In: [msgAddObserverAt] New observer 
// Out: [msgGetObserver] Observer at pos 
U16 position; // In: Position in observer list 

} OBJ_OBSERVER_POS, * P_OB J_OBSERVER_POS ; 

objNull is returned if the position is not in the observer list. 



msgNumObservers 

Passes back the number of observers for this object. 

Takes PJJ16, returns STATUS. 

♦define msgNumObservers MakeMsg (clsObject, 72) 



msgAdded 

Sent to the observer when it is added to an object s observer list. 
Takes OBJECT, returns STATUS. Category: observer notification, 
♦define msgAdded MsgNoError (MakeMsg(clsObject, 66)) 



msgRemoved 

Sent to the observer when it is removed from an object's observer list. 
Takes OBJECT, returns STATUS. Category: observer notification, 
tdefine msgRemoved MsgNoError (MakeMsg (clsObject, 68)) 



msgChanged 

Generic message that can be used to notify observers that a change has occurred. 
Takes OBJECT, returns STATUS. Category: observer notification, 
♦define msgChanged MsgNoError (MakeMsg(clsObject, 76)) 



msgNotUnderstood 

Sent by clsObject when an unrecognized message is received. 

Takes P_MSG_NOT_UNDERSTOOD, returns STATUS. 

♦define msgNotUnderstood MakeMsg (clsObject, 50) 

Argy merits typedef struct MSG_NOT_UNDERSTOOD { 

MESSAGE msg; // In: Message not understood 

P_ARGS pArgs; // In: Args of message 

} MSG_NOT_UNDERSTOOD, * P_MSG_NOT_UNDERSTOOD ; 

Hetyrri Value stsNotUnderstood Always returned by clsObject when this message reaches clsObject. 
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Message wild cards 

Used to define a class wild card and as a table wild card. 

tdefine objWildCard -1 

Wild card for clsObject. 

tdefine clsObjWildCard MakeMsg (clsObject, objWildCard) 

Wild card for clsClass. 

tdefine clsClsWildCard MakeMsg (clsClass, objWildCard) 

Functions 



ObjectCall 

Maps the message to the object's method (MsgHandler) and calls it with pArgs. 

Returns STATUS. 

function Prototype STATUS EXPORTED ObjectCall ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs 

); 

ietum ¥oi$ie stsBadObject Object was invalid. 

stsScopeViolation Object owned by a different task and does not have objCapCall set. 

ObjectCallAncestorCtx 

Calls the next ancestor in the class chain. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectCallAncestorCtx ( 
CONTEXT ctx 

); 
Comments Developers usually can avoid calling this explicitly by specifying objCallAncestorBefore or (for a few 

messages) objCallAncestorAfter in the method table. Occasionally, you need to call your ancestor in the 
middle of things, and this is the call you do it with. 

See Abo ObjectCallAncestor 

Return Value stsBadContext if ctx parameter is bad. 

ObjectCallAncestor 

Calls the ancestor with the parameters supplied. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectCallAncestor ( 

MESSAGE msg, 

OBJECT self, 

P_ARGS pArgs, 

CONTEXT ctx 
); 

Comments In general you should use ObjectCallAncestorCtx(). 

Return Vobe stsBadContext if ctx parameter is bad. 
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ObjectSend 3 

Generalized version of ObjectCall() that works across tasks boundaries. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSend ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, //In only: Not updated 

SIZEOF lenArgs 

); 

Comments The pArgs block is copied into the address space of the task that owns the object and an ObjectCall() is 

executed in that tasks context. If lenArgs equals 0, pArgs block is not copied and the pointer is passed 
directly. In this case, pArgs must point to global storage. 

While the current task is waiting for ObjectSend() to return, the task will continue to dispatch messages 
sent to objects owned by the task. This allows sending to an object in another task, which in turns sends 
to an object owned by the current task, without deadlock. 

Return Value stsProtectionViolation objCapSend is disabled. 

stsSencTTasklnvalid Object's owning task is invalid. 

stsTaskTerminated While waiting for a reply the object's task died. 

ObjectSendUpdate 

Same as ObjectSend (), additionally the pArgs block is copied back to the current task. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendUpdate ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, // In/Out: Updated 

SIZEOF lenArgs 

); 



ObjectSendU32 

Same as ObjectSend() without the length arg, lenArgs = 0. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendU32 ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs // In only: Not updated 

); 



ObjectSendTask 

Same as ObjectSend() except the task is specified explicitly. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendTask ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, //In only: Not updated 

SIZEOF lenArgs, 

0S_TASK_ID task 

); 
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Comments For experts only: Use this routine with care, the task of the object is ignored. ObjectSendTask() allows 

sending to well-known process-globals from outside the process, such as, theProcess. You might use this 
to communicate with theUndoManager in an embedded application. 

ObjectSendUpdateTask 

Same as ObjectSendTask(), additionally the pArgs are updated. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendUpdateTask ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, // In/Out: Updated 

SIZEOF lenArgs, 

OS_TASK_ID task 
); 



Experts only, use this routine with care. 



ObjectPost 

Posts a message to the object via the system input queue. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPost ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs 

); 

Comments ObjectPost() is similar to ObjectSend() but the message delivery is deferred and the current task 

continues to run. Because the current task does not wait, it is not possible to return a status value or 
pArgs. 

The most common use of ObjectPost() is to delay the effect of a msgDestroy. For example, if a button 
sends you a message when it is pressed, and you want to destroy the button at that point, you cannot use 
ObjectCall() to send msgDestroy to it until after you have returned from processing the message the 
button sent. If you ObjectPost() the msgDestroy, this guarantees the button won't receive it until you 
have returned. 

ObjectPost() is synchronized with respect to the input system. A posted message is placed in the system 
input queue. When the message reaches the head of the queue it is sent to the object in the context of 
the task that owns the object. A posted message is typically dispatched by a task's top-level dispatch loop. 
If the task is already processing a message or waiting for a reply to a sent message the posted message is 
queued. The one exception is when the input system is running system modal, in this case the posted 
messages are delivered to any dispatch loop. Dispatch loops are created whenever an ObjectSend() is 
waiting for a reply. The side effect is that any task that is running concurrently may receive a posted 
message at any time. 



CLSMGR.H 29 « 

O 

Functions £ 



ObjectPostU32 3 

Same as ObjectPost() without the length arg, lenArgs = 0. 
Returns STATUS. 



Function Prototype STATUS EXPORTED Ob jectPostU32 ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs 

); 



ObjectPostTask 

Same as ObjectPost() except the task is specified explicitly. 
Returns STATUS. 



Function Prototype STATUS EXPORTED ObjectPostTask ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

0S_TASK_ID task 
); ' 

Comments For experts only: Use this routine with care, the owning task of the object is ignored. ObjectPostTask() 

allows posting to WKN process-globals from outside the process, such as, theProcess. 

ObjectPostAsync 

Similar to ObjectPost() but not synchronized with the input system. 

Returns STATUS. 

function Prototype STATUS EXPORTED ObjectPostAsync ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs 

); 

Comments This call causes concurrency and all the difficulties associated with it. 

One of these difficulties, described in detail under ObjectPost, is the handling of posted messages when 
the input system is running system modal. 

ObjectPostAsyncTask 

Same as ObjectPostAsync() except the task is specified explicitly. 

Returns STATUS. 

function Prototype STATUS EXPORTED ObjectPostAsyncTask ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

0S_TASK_ID task 
); 

Comments This call causes concurrency and all the difficulties associated with it. 
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For experts only: Use this routine with care, the owning task of the object is ignored. 
ObjectPostAsyncTaskO allows posting to WKN process-globals from outside the process, such as, 
theProcess. 

ObjectPostDirect 

Similar to ObjectPostAsyncO but can be dispatched by any dispatch loop. 

Returns STATUS. 

iction Prototype STATUS EXPORTED Ob jectPostDirect ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs 

); 

rwments This call causes concurrency and all the difficulties associated with it. 

One of these difficulties, described in detail under ObjectPost, is the handling of posted messages when 
the input system is running system modal. 

ObjectPostDirectTask 

Same as ObjectPostDirect() except the task is specified explicitly. 

Returns STATUS. 

isfiort Prototype STATUS EXPORTED ObjectPostDirectTask ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

OS_TASK_ID task 
); 

mmenis This call causes concurrency and all the difficulties associated with it. 

For experts only: Use this routine with care, the owning task of the object is ignored. 
ObjectPostDirectTask() allows posting to WKN process-globals from outside the process, such as, 
theProcess. 

^___k — 

Writes the instance data for self in a protected area. 

Returns STATUS. 

iction Prototype STATUS EXPORTEDO Ob jectWrite ( 
OBJECT self, 

CONTEXT ctx, 

PJJNKNOWN pData 
); 

mm ¥alme stsBadContext Invalid context. 
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ObjectWritePartial 

Updates part of the instance data for self in a protected area. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO ObjectWritePartial ( 

OBJECT self, 

CONTEXT ctx, 

PJJNKNOWN pData, 

SIZEOF offset, 

SIZEOF length 
); 

Return Value stsBadContext Invalid context. 



ObjectRead 

Copies the instance data from protected storage into pBuf. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectRead ( 
OBJECT self, 

CONTEXT ctx, 

PJJNKNOWN pBuf 

); 
Comments The pData pointer passed into the MsgHandler is a faster way to read the protected data. 

ObjectPoke 

Writes the object's instance data. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO ObjectPoke ( 
OBJECT object, 

P_MSG classMsgTable, // Address of the class's table 

OBJ_KEY key, // Key for the class 

PJJNKNOWN pBuf 
); 

Comments Copies pBuf into the instance data block for the class specified. 

ietyrn Value stsBadAncestor ClassMsgTable did not correspond to an ancestor. 

stsProtectionViolation Key does not open the object. 

ObjectPeek 

Reads the object's instance data. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPeek ( 
OBJECT object, 

P_MSG classMsgTable, 

OBJ_KEY key, 

PJJNKNOWN pBuf 
); 

Comments Copies the instance data block for the class specified into pBuf. 

ftetyrm ¥oSye stsBadAncestor ClassMsgTable did not correspond to an ancestor. 

stsProtectionViolation Key does not open the object. 
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ObjectOwner 

Returns the object's owner. 

Returns STATUS. 

Function Prototype OS_TASK_ID EXPORTED ObjectOwner ( 
OBJECT object 

); 



ObjectValid 

Returns stsOK if the object is validate, otherwise an error is returned. 

Returns STATUS. 

Function? Prototype STATUS EXPORTED ObjectValid ( 
OBJECT object 

); 

JF Default MsgHandlers 

Default MsgHandler that always returns stsOK. 

Function Prototype MsgHandler (St sQKMsgHandler) ; 

Default MsgHandler that always returns stsFailed. 
Fynction Prototype MsgHandler (St sFailedMsgHandler) ; 

Default MsgHandler that always returns stsReqNotSupported. 
Fynction Prototype MsgHandler (StsReqNotSupportedMsgHandler) ; 

Default MsgHandler that always returns stsNotYetlmplemented. 
Function Prototype MsgHandler (StsNotYetlmplemented) ; 

Default MsgHandler that always returns stsMessagelgnored. 
Fynction Prototype MsgHandler (St sMessagelgnoredMsgHandler) ; 

its for Generating Symbolic Names 

These routines are very useful for debugging. It is MUCH more useful to be able to print 
"stsBadParameter" instead of some 32-bit hex number. 

ClsStsToString 

Takes a STATUS and returns its symbolic name or [wkn=num:sts=num]. 

Returns P_STRING. 

Function Prototype P_STRING EXPORTED ClsStsToString ( 
STATUS sts, 
P_STRING pStr 

); ■ 
Comments Returns either an internal pointer to a symbolic name or the pArgs buffer. If a symbolic name is not 

found, a string [wkn=num:sts=num] is constructed in the pArgs buffer. 

Symbolic names are added via ClsMgrSymbolsInitQ. 
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ClsMsgToString 3 

Takes a message and returns its symbolic name or [wkn=num:msg=num]. 

Returns P_STRING. 

Function Prototype P_STRING EXPORTED ClsMsgToString ( 
MESSAGE msg, 

P_STR5NG pStr 

); 
Comments Returns either an internal pointer to a symbolic name or the pArgs buffer. If a symbolic name is not 

found, a string [wkn=num:msg=num] is constructed in the pArgs buffer. 

Symbolic names are added via ClsMgrSymbolsInit(). 

ClsTagToString 

Takes a message and returns its symbolic name or [wkn=num:tag=num] . 

Returns P_STRING. 

function Prototype P_STRING EXPORTED ClsTagToString ( 
TAG tag, 

P_STRING pStr 
); 

Comments Returns either an internal pointer to a symbolic name or the pArgs buffer. If a symbolic name is not 

found, a string [wkn=num:tag=num] is constructed in the pArgs buffer. 

Currently, TAGs and MSGs are kept in the same list. If a TAG and MSG have the same value then first 
one found will be displayed. This may change in the future. 

Symbolic names are added via ClsMgrSymbolsInitQ. 



ClsObjToString 

Takes an OBJECT and returns its symbolic name or [type:num:num]. 

Returns P_STRING. 

Function Prototype P_STRING EXPORTED ClsOb jToString ( 
OBJECT object, 

P_STRING pStr 
); 

Comments Returns either an internal pointer to a symbolic name or the pArgs buffer. If a symbolic name is not 

found, a string [type=num:num] is constructed in the pArgs buffer. 

Symbolic names are added via ClsMgrSymbolsInit(). 

ObjectlnfoString 

Takes an OBJECT and returns its symbolic name and additional information. 

Returns P_STRING. 

Function Prototype P_STRING EXPORTED ObjectlnfoString ( 
OBJECT object, 

P_STRING pStr 
); 

Comments Formats is the first if the name is found, and the second if not: 

name (cls=name or [type=num:num] ) 
[type=num:num] (cls=name or [type=num:num] ) 
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Return Value stsBadObject Parameter is not an object. 



ClsStringToSts 

Takes a symbolic name as a string and returns the corresponding STATUS. 

Returns STATUS. 

mtfmn Prototype STATUS EXPORTED ClsStringToSts ( 
P_STRING sts 

); 



ClsStringToMsg 

Takes a symbolic name as a string and returns the corresponding message. 
Returns MESSAGE. 

Function Prototype MESSAGE EXPORTED ClsStringToMsg ( 
P_STRING msg 
); 



ClsStringToTag 

Takes a symbolic name as a string and returns the corresponding tag. 

Returns TAG. 

Function Prototype MESSAGE EXPORTED ClsStringToTag( 
P_STRING tag 
); 

Comments Currently, TAGs and MSGs are kept in the same list. If a TAG and MSG have the same value then first 

one found will be displayed. This may change in the fixture. 

ClsStringToObj 

Takes a symbolic name as a string and returns the corresponding OBJECT. 

Returns OBJECT. 

Function Prototype OBJECT EXPORTED ClsStringToObj ( 
P_STRING object 
); 



ClsSymbolsInit 

Adds three arrays of symbolic names (OBJECT, MSG, STATUS) to the database. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO ClsSymbolsInit ( 
P_STRING type, 

P_CLS_SYM_OBJ obj Symbols, 

P_CLS_SYM_MSG msgSymbols, 

P_CLS_SYM_STS stsSymbols 

); 

Comments Each group of arrays is labelled with a tag. If two groups have the same tag, the last group to be added 

replaces the earlier group. The arrays must be in shared, user visible memory. 

Uetum ¥«Ioe stsBadParam symbols were not in shared, user visible memory 
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^Low-Level Task Dispatch Routines 



Ob j ectMsgLoop 

Receives and dispatches object messages forever. 
Returns STATUS. 

tdefine ObjectMsgLoopO ObjectMsgDispatch(pNull) 

Comments If you create a sub-task with OSSubTaskCreateQ, and you want that subtask to be able to receive 

messages, then you have to make it call this routine. ObjectMsgLoopO never returns. It just sits there 
waiting for messages generated by input events or sent from other processes and calling the appropriate 
local message handler for each one in turn. Even if you never use this directly, knowing that it exists 
makes it much easier to understand the difference between ObjectCall, ObjectPost, and ObjectSend. 

Return Value stsBadParam Bad ITMSG_INFO parameter. 



ObjectMsgDispatch 



Dispatches object message received by OSITMsgReceiveQ. 
Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectMsgDispatch (P_OS_ITMSG_INFO pITMsg) ; 

Return Voloe stsBadParam Bad ITMSG_INFO parameter. ITMsg type must be one of osClsmgrSend or 

osClsmgrPost. 



ObjectMsgDispatchlnfo 

Passes back information on the current ObjectMsgDispatch frame. 
Returns STATUS. 



function Prototype STATUS EXPORTED ObjectMsgDispatchlnfo ( 



OS_ITMSG_INFO 
U32 



plnfo, 
pLevel 



// 
// 
// 
// 
// 



Out: ITMSG_INFO for requested frame 

In/Out: requested frame 

In: requested dispatch frame, 

maxU32 = current, 1 = top level 
Out: actual level of dispatch frame. 



// (.asm) 



); 

Enum32 (SENDJTYPE) 
{ 

objSendNoUpdate = flagO, 

objSendUpdate = flagl, 

objPostAsync = flag2, 

objPostDirect = flag3, 

objSendMax = flaglO 

}; 

Used by ObjectMsgExtract() and ObjectmsgAlterQ. All fields are out parameters for ObjectMsgExtract 
and in parameters of ObjectMsgAlter. The token field is currently not used and not settable by 
ObjectMsgAlter. 

typedef struct OBJ_DISPATCH_INFO { 

MESSAGE msg; 

OBJECT object; 

P_ARGS pArgs; 

U32 length; 

U32 token; 

SENDJTYPE type; 
} OBJ DISPATCH INFO, *P OBJ DISPATCH INFO; 
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stsBadParam Bad ITMSGJNFO parameter. 

stsFailed Not inside a dispatch loop or invalid frame number 



ObjectMsgExtract 

Extracts the interesting ObjectSend fields from the ITMsg packet. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectMsgExtract ( 
P_OS_ITMSG_INFO pITMsg, 

P_OBJ_DISPATCH_INFO plnfo 
); 



Refyrn Voioe 



stsBadParam Bad ITMSGJNFO parameter. 



ObjectMsgAlter 

Alters the ObjectSend fields of the ITMsg packet. 
Returns STATUS. 



Function Prototype STATUS EXPORTED ObjectMsgAlter ( 
P_OS_ITMSG_INFO pITMsg, 

P_OBJ_DISPATCH_INFO plnfo 

); 



These structs are used by the method compiler, outside of Penpoint. 



Enuml 6 (MSG_HANDLER_FLAGS ) { 

objCallAncestorBefore = flagO, 
objCallAncestorAfter = flagl, 
objDereflData = flag2, 
objInheritMethod = flag3, 
objClassMessage = flag4, 
objSaveSpace = flag5, 

objSaveTime = flag6 

}; 

typedef struct MSG_INFO { 
MESSAGE msg; 

P_U8 functionName; 

MSG_HANDLER_FLAGS flags; 

} MSG_INFO, * P_MSG_INFO; 

typedef struct CLASS_INFO { 
P_U8 tableName; 

P_MSG_INFO msgTable; 
U32 flags; 

} CLASS INFO, * P CLASS INFO; 



// Call ancestor before this handler 

// Call ancestor after this handler 

// No-op 

// No-op 

// Handle messages sent to a class 

// Optimize for space 

// Optimize for time 



// name to use for compiled table 
// message table to compile 
//no flags, must be set to zero 



Return VoSue 



stsBadParam Bad ITMSGJNFO parameter. 
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bugging Support g 

Same as ObjectCall() but prevents tracing (i.e., no debug output for /DO) 
Returns STATUS. 

Function Prototype STATUS EXPORTED Ob jectCallNoDebug ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs 
); 
tdefine objMaxCallsDepth 10 

typedef struct OBJ_STATISTICS { 

U32 numOb j Reads; 

U32 numObjWrites; 

U32 numObjPeeks; 

U32 numOb j Pokes, • 

U32 numObjCalls; 

U32 numOb j Sends; 

U32 numObjPosts; 

U32 depthOb jCalls [objMaxCallsDepth] ; 

U32 numObjMaxDepth; 
} OBJ_STATISTICS, *P_OBJ_STATISTICS; 

ClsClearStatistics 

Zeros the statistics gathering counters. 
Returns STATUS. 

teflon Prototype STATUS EXPORTED ClsClearStatistics (void) ; 



ClsDumpStatistics 

Prints the current value of the statistics. 
Returns STATUS. 

lion Prototype STATUS EXPORTED ClsDumpStatistics (void) ; 



ClsStatistics 

Passes back the current value of the statistics in stats parameter. 
Returns STATUS. 

ctioti Prototype STATUS EXPORTED ClsStatistics (P OBJ STATISTICS stats); 



ClsSetStatistics 

Resets the value of the statistics to stats parameter. 

Returns STATUS. 
Function Prototype STATUS EXPORTED ClsSetStatistics (P_OBJ_STATISTICS stats); 
Comments By calling ClsStatisticsQ at the beginning of a routine and ClsSetStatistics () at the end selected routines 



can be exempted from statistics gathering. 
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Debugging Macros 

The debugging macros are short-hand for a call to the appropriate function followed by a conditional 
test and action. All the message passing functions have macros that: return if there is an error (Ret), 
jump to a label on an error (Jmp) and test for an error and return the value (OK). ObjectCall and 
ObjectCallAncestor have two additional macros, Failed and Chk. 

Standard GO error recovery is done by using the Ret() form as long as there's nothing to clean up and 
then using the Jmp() form to jump to a label at the bottom of the routine that knows how to clean up. 
Note that both Ret() and Jmp() forms use Warn() forms of their respective calls, so any sts < stsOK 
generates an error message if DEBUG is set. 

ObjectCall 

tdefine ObjCallRet (m, o,p,s) \ 

if (((s) = ObjCallWarn(m,o,p) ) < stsOK) return s; else 

tdefine ObjCallJmp(m, o,p,s,x) \ 

if ( ( (s) = ObjCallWarn(m, o,p) ) < stsOK) goto x; else 

tdefine ObjCallOK(m,o,p,s) ( (s = ObjCallWarn(m ; o,p) ) >= stsOK) 

tdefine ObjCallFailed(m,o,p,s) ((s = Ob jCallWarn (m, o,p) ) < stsOK) 

tdefine ObjCallChk(m,o,p,s) ((s = ObjectCall (m, o,p) ) < stsOK) 

ObjectCallAncestor 

tdefine ObjCallAncestorRet (m,o,p,c, s) \ 

if ( ( (s) = ObjCallAncestorWarn(m,o,p,c) ) < stsOK) return s; else 
tdefine ObjCallAncestor Jmp (m, o,p,c,s,x) \ 

if (((s) = ObjCallAncestorWarn(m,o,p,c) ) < stsOK) goto x; else 
tdefine Ob jCallAncestorOK (m, o,p,c,s) \ 

((s = ObjCallAncestorWarn(m, o,p,c) ) >= stsOK) 
tdefine ObjCallAncestorFailed(m, o,p,c,s) \ 

( (s = ObjCallAncestorWarn(m, o,p,c) ) < stsOK) 
tdefine Ob jCallAncestorChk (m, o,p,c,s) \ 

( (s = ObjectCallAncestor (m, o,p,c) ) < stsOK) 

tdefine ObjCallAncestorCtxRet (c,s) \ 

if (((s) = ObjCallAncestorCtxWarn(c) ) < stsOK) return s; else 
tdefine ObjCallAncestorCtxJmp(c,s,x) \ 

if (((s) = ObjCallAncestorCtxWarn(c) ) < stsOK) goto x; else 
tdefine ObjCallAncestorCtxOK(c,s) \ 

((s = ObjCallAncestorCtxWarn(c) ) >= stsOK) 

ObjectSend 

tdefine ObjSendRet (m, o,p,l,s) \ 

if (((s) = ObjSendWarn(m,o,p,l) ) < stsOK) return s; else 

tdefine Ob j Send Jmp (m, o,p,l,s,x) \ 

if (((s) = ObjSendWarn(m, o,p,l) ) < stsOK) goto x; else 
tdefine ObjSendOK(m, o,p,l,s) ( (s = ObjSendWarn(m,o,p,l) ) >= stsOK) 

ObjectSendUpdate 

tdefine Ob jSendUpdateRet (m, o, p, 1, s) \ 

if (((s) = ObjSendUpdateWarn(m, o,p,l) ) < stsOK) return s; else 

tdefine ObjSendUpdateJmp(m, o,p,l,s,x) \ 

if (((s) = ObjSendUpdateWarn(m, o,p,l) ) < stsOK) goto x; else 

tdefine Ob jSendUpdateOK(m,o,p,l,s) ( (s = ObjSendUpdateWarn(m,o,p,l) ) >= stsOK) 

ObjectSendTask 

tdefine ObjSendTaskRet (m,o,p,l,t,s) \ 

if (((s) = Ob jSendTaskWarn (m, o,p,l,t)) < stsOK) return s; else 
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♦define ObjSendTaskJmp(m,o,p,l,t,s,x) \ < 

if (((s) = ObjSendTaskWarn(m, o,p,l,t) ) < stsOK) goto x; else <■» 

♦define ObjSendTaskOK(m,o,p,l,t,s) ( (s = ObjSendTaskWarn(m,o,p,l,t) ) >= stsOK) 

ObjectSendUpdateTask 

♦define ObjSendUpdateTaskRet (m, o,p, l,t,s) \ 

if ( ( (s) = ObjSendUpdateTaskWarn(m, o,p,l,t) ) < stsOK) return s; else 

♦define ObjSendUpdateTaskJmp(m, o,p, l,t,s,x) \ 

if ( ( (s) = ObjSendUpdateTaskWarn^O/Pfl/t) ) < stsOK) goto x; else 

♦define ObjSendUpdateTaskOK(m, o,p,l,t,s) \ 

((s = ObjSendUpdateTaskWarn(m, o,p,l,t) ) >= stsOK) 

ObjectSendU32 

♦define ObjSendU32Ret(m,o,p,s) \ 

if (((s) = ObjSendU32Warn(m,o,p) ) < stsOK) return s; else 

♦define ObjSendU32Jmp(m, o,p, s,x) \ 

if (((s) = ObjSendU32Warn(m, o,p) ) < stsOK) goto x; else 
♦define ObjSendU320K(m,o,p, s) ((s = ObjSendU32Warn(m,o,p) ) >= stsOK) 

ObjectPost 

♦define Ob jPostRet (m,o,p,l, s) \ 

if (((s) = Ob jPostWarn (m, o,p,l) ) < stsOK) return s; else 

♦define Ob jPost Jmp (m, o,p,l,s,x) \ 

if (((s) = ObjPostWarn (m, o,p, 1) ) < stsOK) goto x; else 

♦define ObjPostOK(m,o,p,l,s) ((s = ObjPostWarn (m,o,p,l)) >= stsOK) 
Obj ectPostAsync 

♦define ObjPostAsyncRet (m,o,p, l,s) \ 

if (((s) = ObjPostAsyncWarn(m,o,p, 1) ) < stsOK) return s; else 
♦define ObjPostAsyncJmp(m, o,p,l,s,x) \ 

if (((s) = ObjPostAsyncWarn(m,o,p, 1) ) < stsOK) goto x; else 
♦define ObjPostAsyncOK(m,o,p,l,s) ( (s = Ob jPostAsyncWarn (m, o,p, 1) ) >= stsOK) 

ObjectPostDirect 

♦define ObjPostDirectRet (m,o,p,l,s) \ 

if (((s) = ObjPostDirectWarn(m,o,p,l) ) < stsOK) return s; else 

♦define ObjPostDirectJmp(m,o,p,l,s,x) \ 

if ( ( (s) = ObjPostDirectWarn(m,o,p, 1) ) < stsOK) goto x; else 
♦define ObjPostDirectOK(m,o,p,l,s) ((s = ObjPostDirectWarn(m,o,p, 1) ) >= stsOK) 

ObjectPostU32 

♦define ObjPostU32Ret (m,o,p,s) \ 

if (((s) = ObjPostU32Warn(m,o,p) ) < stsOK) return s; else 

♦define Ob jPostU32 Jmp (m, o,p,s,x) \ 

if (((s) = ObjPostU32Warn(m,o,p)) < stsOK) goto x; else 
♦define ObjPostU320K(m,o,p,s) ( (s = ObjPostU32Warn(m,o,p) ) >= stsOK) 



40 PENPOINT API REFERENCE 

Part 1 / Class Manager 



Debugging Helper Functions 
(with /DDEBUG) 

#if defined DEBUG | | defined CLSMGR COMPILE 



ObjectCallWarning 

Same as ObjectCall(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

mtimm Prototype STATUS EXPORTED ObjectCallWarning ( 
MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

P_STRING fn, 
U16 In 

); 



smments In general, ObjCallWarn macro should be used to call this routine. 



ObjectCallNoDebugWarning 

Same as ObjectCallNoDebugO, additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectCallNoDebugWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjCallNoDebugWarn macro should be used to call this routine. 



ObjectCallAncestorCtxWarning 

Same as ObjectCallAncestorCtx(), additionally prints a debugging message if status less than stsOK. 
Returns STATUS. 

STATUS EXPORTED ObjectCallAncestorCtxWarning ( 

CONTEXT ctx, 

P_STRING fn, 

U16 In 

); 

In general, ObjCallAncestorCtxWarn macro should be used. 



ObjectCallAncestorWarning 

Same as ObjectCallAncestor(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

iction Prototype STATUS EXPORTED ObjectCallAncestorWarning ( 

MESSAGE msg, 

OBJECT Object, 

P_ARGS pArgs, 

CONTEXT ctx, 

P_STRING fn, 

U16 In 
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Comments In general, ObjCallAncestorWarn macro should be used. 3 



u 



ObjectSendWarning 

Same as ObjectSend(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

P_STRING fn, 

U16 In 
); 



Comments In general, ObjectSendWam macro should be used. 



ObjectSendUpdateWarning 

Same as ObjectSendUpdate(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendUpdateWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectSendUpdateWarn macro should be used. 

ObjectSendTaskWarning 

Same as ObjectSendTask(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendTaskWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

OS_TASK_ID task, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectSendTaskWarn macro should be used. 
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ObjectSendUpdateTaskWarning 

Same as ObjectSendUpdateTask(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectSendUpdateTaskWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

OS_TASK_ID task, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectSendUpdateTaskWarn macro should be used. 



ObjectPostWarning 

Same as ObjectPost(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPostWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectPostWarn macro should be used. 

ObjectPostAsyncWarning 

Same as ObjectPostAsync(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPostAsyncWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

P_STRING fn, 

U16 In 
); 

comments In general, ObjectPostAsyncWarn macro should be used. 

ObjectPostDirectWarning 

Same as ObjectPostDirect(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPostDirectWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectPostDirectWarn macro should be used. 
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ObjectPostTaskWarning 

Same as ObjectPostTask(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPostTaskWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

OS_TASK_ID task, 

P_STRING fn, 

U16 In 
); 



Comments In general, ObjectPostTaskWarn macro should be used. 



ObjectPostAsyncTaskWarning 

Same as ObjectPostAsyncTask(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPostAsyncTaskWaming( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

OS_TASK_ID task, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectPostAsyncTaskWarn macro should be used. 



ObjectPostDirectTaskWarning 

Same as ObjectPostDirectTask(), additionally prints a debugging message if status less than stsOK. 

Returns STATUS. 

Function Prototype STATUS EXPORTED ObjectPostDirectTaskWarning ( 

MESSAGE msg, 

OBJECT object, 

P_ARGS pArgs, 

SIZEOF lenArgs, 

OS_TASK_ID task, 

P_STRING fn, 

U16 In 
); 

Comments In general, ObjectPostDirectTaskWarn macro should be used. 

ObjectWarning 

Prints object warning message. Low-level routine. 
Returns nothing. 
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Function Prototype void EXPORTED Ob ject Warning ( 



P_STRING 


label, 


MESSAGE 


msg, 


OBJECT 


object, 


P_ARGS 


pArgs , 


STATUS 


sts, 


P STRING 


fn, 


U16 


In 



>; 

Debugging Helper Macros (with /DDEBUG) 

Conditional macros. Under /DDEBUG generates indirect calls via debugging functions, without 
/DDEBUG generates direct calls. 

The only difference between the Warn() form and the plain form of these calls is that Warn() prints an 
error message if sts < stsOK AND the module was compiled for DEBUG. Use of the Warn() form is 
strongly encouraged. 

ObjectCall 

#define ObjCallWarn(m,o,p) ObjectCallWarning(m,o,p, FILE , LINE ) 

#define ObjCallNoDebugWarn(m, o,p) \ 

Ob jectCallNoDebugWarning (m, o,p, FILE , LINE ) 

#define Ob jCallAncestorCtxWarn (c) \ 

ObjectCallAncestorCtxWarning (c, FILE , LINE ) 

tdefine Ob jCallAncestorWarn (m, o,p,c) \ 

ObjectCallAncestorWarning (m, o,p, c, FILE , LINE ) 

ObjectSend 

#define ObjSendWarn (m, o,p, 1) ObjectSendWarning(m, o,p, 1, FILE , LINE ) 

#define ObjSendUpdateWarn(m, o,p,l) \ 

Ob jectSendUpdateWarning (m, o, p, 1, FILE , LINE ) 

tdefine ObjSendTaskWarn(m,o,p,l,t) \ 

Ob jectSendTaskWarning (m, o, p, 1, t , FILE , LINE ) 

tdefine ObjSendUpdateTaskWarn(m, o,p,l,t) \ 

Ob ject SendUpdateTaskWarning (m, o , p, 1 , t , FILE , LINE ) 

tdefine ObjSendU32Warn (m, o,p) ObjectSendWarning (m, o,p, OL, FILE , LINE ) 

ObjectPost 

tdefine ObjPostWarn (m, o,p, 1) ObjectPostWarning (m, o,p, 1, FILE , LINE ) 

tdefine Ob jPostAsyncWarn (m, o,p,l) \ 

ObjectPostAsyncWarning(m, o,p,l, FILE , LINE ) 

tdefine ObjPostDirectWarn(m, o,p,l) \ 

ObjectPostDirectWarning(m,o,p,l, FILE , LINE ) 

tdefine ObjPostTaskWarn(m,o,p,l,t) \ 

ObjectPostTaskWarning(m,o,p,l,t, _FILE , LINE ) 

tdefine ObjPostAsyncTaskWarn(m, o,p,l,t) \ 

ObjectPostAsyncTaskWarning(m, o,p, 1, t, FILE , LINE ) 

tdefine Ob jPostDirectTaskWarn (m, o,p,l,t) \ 

Ob jectPostDirectTaskWarning (m, o, p, 1, t , FILE , LINE ) 

tdefine ObjPostU32Warn(m,o,p) ObjectPostWarning (m,o,p, OL, FILE , LINE ) 

telse // DEBUG 
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pr Debugging Helper Macros s 

(without /DDEBUG) 

ObjectCall 

♦define ObjCallWarn(m,o,p) ObjectCall (m,o,p) 
♦define Ob jCallNoDebugWarn (m, o,p) ObjectCall (m,o,p) 
♦define ObjCallAncestorCtxWarn(c) ObjectCallAncestorCtx(c) 
♦define ObjCallAncestorWarn(m,o,p,c) ObjectCallAncestor(m,o,p,c) 

ObjectSend 

♦define ObjSendWarn(m, o,p, 1) ObjectSend (m, o,p, 1) 

♦define ObjSendUpdateWarn(m,o,p,l) Ob jectSendUpdate (m, o,p,l) 

♦define ObjSendTaskWarn(m, o,p,l,t) ObjectSendTask(m,o,p,l,t) 

♦define Ob jSendUpdateTaskWarn (111,0,?, 1, t) Ob jectSendUpdateTask (m, o, p, 1, t) 

♦define ObjSendU32Warn(m,o,p) ObjectSendU32(m,o,p) 

ObjectPost 

♦define Ob jPostWarn (m, o,p,l) ObjectPost (m,o,p,l) 

♦define ObjPostAsyncWarn(m,o,p,l) ObjectPostAsync(m,o,p,l) 

♦define Ob jPostDirectWarn (m, o,p,l) ObjectPostDirect (m, o,p,l) 

♦define ObjPostTaskWarn(m,o,p,l,t) ObjectPostTask(m,o,p,l,t) 

♦define ObjPostAsyncTaskWarn(m,o,p,l,t) Ob jectPostAsyncTask (m, o,p, l,t) 

♦define Ob jPostDirectTaskWarn (m, o, p, 1, t ) Ob jectPostDirectTask (m, o, p, 1, t ) 

♦define ObjPostU32Warn(m, o,p) ObjectPost (m, o,p, OL) 

♦endif // DEBUG 

♦endif 
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This file contains the definitions of some of PenPoint's debugging support. 
The functions described in this file are contained in PENPOINT.LIB. 

Introduction. 

This file contains the definitions of some of PenPoint's debugging support. 

One of the most important characteristics of this package is that many of the macros compile into 
nothing unless the pre-processor variable DEBUG is defined during compilation. 

Debugging Flags. 

As part of its debugging support, PenPoint includes a collection of debugging flags which allow 
developers to control the runtime behavior of their programs. 

For convenience, the debugging flags are broken into "sets" of 32 one bit flags. In PenPoint 1.0, there 
are 255 sets; future versions of PenPoint may have more sets. Some sets are reserved for use by PenPoint 
itself; all other sets are available for use by other developers. The allocation of sets is documented 
elsewhere in this file. 

Setting and Examining Debug Flags. 

The debugging flags can be set via the DebugSet environment variable in PenPoint's environ.ini file. The 
debugging flags can also be set with the "fs" command in the MiniDebugger and DB. (The debugging 
flags can be examined with the "fl" command.) Both the environ.ini file and the PenPoint debuggers 
allow the flag sets to be identified with either a or an 8 bit hexadecimal number. See the PenPoint 
developer's documentation for more information. 



Example. 



The debugging output in the following fragment appears only if the code was compiled with DEBUG 
defined and the debug flag is on. 

As illustrated in this example, most debugging code should surrounded by some sort of conditional 
compilation that causes the debugging code to "disappear" when compiled appropriately. 

if (someCondition) { 

DbgFlag(0x80, Oxl, Debugf ("someCondition is TRUE");) 

} else { 

DbgFlag(0x80, 0x1, Debugf ("someCondition is FALSE");) 



Here's an example of setting debugging flags in PenPoint's environ.ini file: 



DebugSet=/DD8000 /DB800 
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#ifndef DEBUG_INCLUDED 
#define DEBUG_INCLUDED 
tifndef GO_INCLUDED 
tinclude <go.h> 
tendif 



Exported Macros 



DbgFlag 

Executes an expression under control of a debug flag IF the source is compiled with DEBUG defined. 
Returns void.. 

#ifdef DEBUG 

#define DbgFlag (f,v,e) if (DbgFlagGet (f, v) ) e 

#else 

#define DbgFlag (f,v,e) 

tendif 

Comments The DbgFlagO macro is used to execute an expression if (1) the source module was compiled with 

DEBUG defined and (2) if the appropriate debugging flag is turned on at runtime. 



Dbg 

Used to control the compile-time inclusion of debugging code. 
Returns void.. 

#ifdef DEBUG 
tdefine Dbg(x) x 
#else 

#define Dbg(x) 
tendif 

Comments The Dbg() macro is used to comment out code when the DEBUG flags is undefined. For example, the 

following code is present if the source file is compiled with DEBUG defined but "disappears" if 
DEBUG is not defined. 

Dbg (Debugf ( "Only shows up in DEBUG version");) 

Used to verify that some runtime condition is true. 
Returns void.. 

tifdef DEBUG 

tdefine ASSERT (cond, str) ( (void) (! (cond) ? \ 

(Debugf ("==> ERROR, File: %s, Line: %d ==> %s\n", \ 

FILE , LINE , str)),l: 0)) 

telse 

tdefine ASSERT (cond, str) 

tendif 

Comments The ASSERT() macro is used to test for conditions and print out a warning if the condition is violated. 

The code "disappears" if the module is compiled without DEBUG being defined. 

5©e Also assert.h 
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Exported Functions 3 

Debugf 

Prints a formatted string on the debug output device, followed by a newline. 
Returns void. 

void CDECL 

Debugf (char* str, . . . ) ; 

* Debugf is very similar to the standard C runtime library function printf() except that (1) Debugf directs 

it output to PenPoint's debug output device and (2) Debugf prints a newline at the end of its output. 

Unless surrounded by something Dbg() or DbgFlagO, Debugf does not disappear, even if compiled 
without DEBUG defined. 

Use DPrintf to avoid having the trailing newline printed. 

See Also DPrintf 



DPrintf 

Prints a formatted string on the debug output device. 
Returns void. 

void CDECL 

DPrintf (char* str, ...); 

Comments DPrintf is very similar to the standard C runtime library function printf() except that DPrintf directs it 

output to PenPoint's debug output device. 

Unless surrounded by something Dbg() or DbgFlagO, DPrintf does not disappear, even if compiled 
without DEBUG defined. 

See Also Debugf 



DbgFlagSet 

Sets the specified flag set to the value of the new flags. 

Returns void. 

void EXPORTED 

Function Prototype DbgFlagSet ( 
U16 set, 
U32 flags) ; 

set flag set selector in the range 0..255, inclusive. (Defined as a U16 to allow for possible future 

expansion.) 

flags new values for the flag set. 

It is unusual for a program to call this function; most developers should set the value of debugging flags 
using the techniques described in the introduction of this file rather than executing this function. 

Unless surrounded by something Dbg() or DbgFlagO, DbgFlagSet does not disappear, even if compiled 
without DEBUG defined. 
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DbgFlagGet 

Returns the state of the indicated flag set ANDed with the flags mask. 

Returns void. 

U32 EXPORTED 

Hon Prototype DbgFlagGet ( 
U16 set, 
U32 flags); 

set flag set selector in the range 0..255, inclusive. (Defined as a U16 to allow for possible future 
expansion.) 

flags flags mask 

Unless surrounded by something Dbg() or DbgFlagO, DbgFlagGet does not disappear, even if compiled 
without DEBUG defined. 



Debugging Flag Set Allocations 



Not to be used by anyone (interferes with parsing process) : 
0x00 
0x09 
OxOA 
OxOD 
OxlA 
0x20 

Reserved for use outside of GO: 

Lower case alphabet, except f, h, i, s, and z. 

0x30 . . 0x39 digits 

0x80 . . OxBF half of the upper range 

Reserved for use by GO 
'f 
'h' 
'i' 

'q' 

's' 
'z' 

everything else 

Here are the allocations within GO's range. See other header files for 
more information on the interpretation of these flags. Most flags only 
have effect if you load the debug versions of DLLs. 

' f ' : GO Application Developer' s Course 

'h': Hwxtool and Insertion Pads 

' q' : Quick Help 

's' : Hwxtool 

'z': Xlate 

'A' : Misc. system use. 

A0001: Print loader information while loading 

'B' : System 



'D' 



'E' 

'G' 
'H' 



'I' 
'J' 
'K' 
'L' 



DEBUG. H 
Debugging Flag Set Allocations 

B0001: Turns uuid cache tracing on 

B0002: Enables OEM app/service installation after warm-boot This 

should only be turned on for tablet hardware; never on the 

SDK! 
B0800: Enables theSelectedVolume disk viewing in Connections 

: ClsMgr 

: Debug system 
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D0001 
D0002 
D0004 
D0008 
D0010 
D0020 
D8000 



D10000: 
D20000: 
D40000: 
D80000000: 



disables all DebugStr output 

disables StringPrint output 

disables System Log output 

disables System Log Non Error output 

disables System Log App Error output 

disables System Log System Error output 

writes output to PENP0INT.LOG, file flushed every n chars 

based on the environment variable DebugLogFlushCount . 

disables mini-debugger in production version of Penpoint 

disables memory statistics gestures (M,N,T) on Bookshelf 

disables A C entering the mini-debugger 

allows logging to log file even if in file system code 

(This may cause deadlocks and is for internal use only) . 



Environment flags 

Application Developer' s Course 

Kernel 

Service and Service Manager 



H0001 
H0002 
H8000 



turns on message tracing in clsService 
turns on message tracing in clsServiceMgr 
run sanity test in service.dll 



Installers (see instlmgr.h) 
Notebook 
UI Toolkit 

PicSegs and TIFF images 
L0001: dumps the TIFF image tags, 
misc. lib 



M0001 
M0002 
M0004 
M0008 
M0100 



tracing in OrderedSetDelete 

tracing in OrderedSetFindMinMax & MaxMin 

tracing in OrderedSetlnsertn 

tracing in OrderedSetSearch 

write/read debug header&trailer when filing ByteArray 



'N' 
'0' 

'Q' 



MiniText 
: Outbox (obxserv and oboxsect) 

O0001: enable automatic activate of outbox Notebook 
: Printing 
: text . dll 

Application Framework 
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'S': Spelling, Proof, and XTemplate systems 



S0001 
S0002 
S0004 
S0010 
S0020 



low-level Spell/Proof debugs 
medium-level Spell/Proof debugs 
high-level Spell/Proof debugs 
XTemplate display inputs 
XTemplate display outputs 



'T' : text.dll 

'U': undo.dll 

'V : text.dll 

'W : Window system 

'X': xfer.lib 

' Y' : TOPS 

'Z' : Handwriting 

'@': Bookshelf 

'=': MiniNote/NotePaper 

'#' : GWin 

' !' : Test Manager 

' $' : File System 

'%': UI Toolkit 

' *.' : Heap Manager 

OxCO: Fax Project 

OxCl : Input 

0xC2 : VKey 

0xC3: System Log trace flag 

0xC4: 2.0 tools 

OxFO: Memory Tests // Internal use only 

OxFl: Memory Tests // Internal use only 

OxFF: C Runtime Library 
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GO.H 



This file contains PenPoint's standard #defines, types and intrinsics. Essentially all PenPoint source files 
must include this file. 

The functions described in this file are contained in PENPOINT.LIB. 

tifndef GO_INCLUDED 
♦define GO INCLUDED 



Standard Definitions 

Static Declarations 

Functions declared STATIC (rather than static) will, when compiled with DEBUG defined, appear in 
map files. 

tifndef DEBUG 

#define STATIC static 

#else 

tdefine STATIC 
#endif 

Function Scope Definitions 



LOCAL: Scope is module wide 

GLOBAL: Scope is subsystem wide 

EXPORTED: Scope is ring wide (either ringO OR ring3) 

EXPORTEDO: Scope is system wide. For public ringO functions. 

RINGCHELPER: Scope is system wide. For private ringO functions. 



#define LOCAL 
tdefine GLOBAL 
#define EXPORTED 
tdefine EXPORTEDO 
tdefine RINGCHELPER 

Null values 

tifndef M_I86 
tdefine NULL 

telse 
tdefine NULL OL 

tendif 

tdefine null 
tdefine pNull 
tdefine ppNull 
tdefine Nil (type) 

Boolean operators 

tdefine AND 
tdefine OR 
tdefine NOT 
tdefine MOD 



STATIC PASCAL 

PASCAL 

PASCAL 

PASCAL 

PASCAL 



// 32 bit compiler 
// 16 bit compiler 



((P_UNKNOWN)0) 

((PP_UNKNOWN)0) 

((type)O) 



II 
j 

% 
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Bit flags. 

These flags can be used with FlagOn, FlagOff, FlagSet, and FlagCIr. 



tdefine 


flagO 


(0x0001) 


tdefine 


flagl 


(0x0002) 


#define flag2 


(0x0004) 


tdefine 


flag3 


(0x0008) 


tdefine 


flag4 


(0x0010) 


tdefine 


flag5 


(0x0020) 


tdefine 


flag6 


(0x0040) 


tdefine 


flag7 


(0x0080) 


tdefine 


flag8 


(0x0100) 


tdefine 


flag9 


(0x0200) 


tdefine 


flaglO 


(0x0400) 


tdefine 


flagl 1 


(0x0800) 


tdefine 


flagl2 


(0x1000) 


tdefine flagl3 


(0x2000) 


tdefine 


flagl4 


(0x4000) 


tdefine 


flagl5 


(0x8000) 


tdefine 


flagl 6 


(0X00010000L) 


tdefine 


flagl7 


(0x00020000L) 


tdefine 


flagl8 


(0x00040000L) 


tdefine 


flagl 9 


(0x00080000L) 


tdefine 


flag20 


(OxOOlOOOOOL) 


tdefine 


flag21 


(0x00200000L) 


tdefine 


flag22 


(0x00400000L) 


tdefine 


flag23 


(0x00800000L) 


tdefine 


flag24 


(OxOlOOOOOOL) 


tdefine 


flag25 


(0x02000000L) 


tdefine 


flag26 


(0x04000000L) 


tdefine 


flag27 


(0x08000000L) 


tdefine 


flag28 


(0X10000000L) 


tdefine 


flag29 


(0x20000000L) 


tdefine 


flag30 


(0x40000000L) 


tdefine 


flag31 


(0x80000000L) 


Limits 






tdefine maxU8 


((U8)0xFF) 


tdefine minS8 


((S8)0x80) 


tdefine 


maxS8 


((S8)0x7F) 


tdefine 


maxU16 


((U16)0xFFFF) 


tdefine 


minS16 


((S16) 0x8000) 


tdefine maxS16 


((S16)0x7FFF) 


tdefine maxU32 


((U32)0xFFFFFFFF) 


tdefine minS32 


((S32) 0x80000000) 


tdefine 


maxS32 


((S32)0x7FFFFFFF) 


Name limits 




tdefine 


maxNameLength 


32 


tdefine nameBufLength 


(maxNameLength+1 ) 



Enums 

Different compilers allocate different amounts of space for an enum. To avoid portability problems, use 
the Enum 16 and Enum32 macros. They guarantee that the enum is 16 bits or 32 bits, respectively. 
Example: 

Enuml6(PRIMARY_COLOR) { 

red, 

green, 

blue 
} 



GO.H 
Typedefs 
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♦define Enuml6(name) typedef S16 name, * P_##name; enum name 
♦define Enum32(name) typedef S32 name, * P_##name; enum name 

Calling Conventions 

#if defined _WATCOMC 

♦define PASCAL pascal 

♦define CDECL cdecl 

♦define Unused (x) (void) (x) 

♦define FunctionPtr (fn) (PASCAL * fn) 

♦define CFunctionPtr(fn) (CDECL * fn) 

♦if defined _386_ 

♦pragma aux pascal IIA " parm routine []\ 
value struct float struct caller [eax] modify [eax ecx edx gs] ; 

♦pragma aux cdecl "_*" parm caller []\ 

value struct float struct caller [eax] modify [eax ecx edx gs]; 

♦endif 
♦elif defined HIGHC 

♦define PASCAL _CC(_REVERSE_PARMS |_CALLEE_POPS_STACK) 

♦define CDECL // Default for the compiler 

♦define Unused (x) 

♦define FunctionPtr (fn) PASCAL (* fn) 

♦define CFunctionPtr(fn) CDECL (* fn) 
♦else 

♦define PASCAL pascal 

♦define CDECL cdecl 

♦define Unused (x) (void) (x) 

♦define FunctionPtr (fn) (* PASCAL fn) 

♦define CFunctionPtr(fn) (* CDECL fn) 
♦endif 



Typedefs 



Unsigned integers 

typedef unsigned char U8, * P_U8, ** PP_U8; 

typedef unsigned short U16, * P_U16, ** PP_U16 

♦ifndef M_I86 // 32 bit compiler 

typedef unsigned int U32, * P_U32, ** PP_U32 

♦else // 16 bit compiler 

typedef unsigned long U32, * P_U32, ** PP_U32 
♦endif 



Signed integers 

typedef signed char 
typedef signed short 
♦ifndef M_I86 

typedef signed int 
♦else 

typedef signed long 
♦endif 



S8, * P_S8, ** PP_S8; 
S16, * P_S16, ** PP_S16 
// 32 bit compiler 
S32, * P_S32, ** PP_S32 
// 16 bit compiler 
S32, * P S32, ** PP S32 



// 8-bit unsigned 

// 16-bit unsigned 

// 32-bit unsigned 

// 32-bit unsigned 



// 8 -bit signed 

// 16-bit signed 

// 32 -bit signed 

// 32 -bit signed 



Wide characters. In PenPoint 1.0 these are 8 bit values. In PenPoint 2.0 and forward they are 16 bit 
values. 



typedef U8 
typedef P_U8 
typedef P_CHAR* 


CHAR; 

P_CHAR; 

PP_CHAR; 


8 bit Characters 




typedef U8 
typedef P_U8 
typedef P_CHAR8* 


CHAR8; 
P CHAR8; 
PP_CHAR8; 



// These are guaranteed to stay 8 -bit 
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16 bit Characters 

typedef U16 
typedef P_U16 
typedef P CHAR16* 



CHAR16; // These are guaranteed to stay 16-bit 

P_CHAR16; 

PP CHAR16; 



STRING; 
P_STRING; 
PP STRING; 



Strings 

typedef U8 
typedef P_U8 
typedef P_STRING* 

SIZEOF is the type returned by the SizeOf. It is guaranteed to be 32 bits. 

typedef U32 SIZEOF, * P_SIZEOF; 

Pointer to an opaque entity 



typedef void* 
typedef P UNKNOWN* 



PJJNKNOWN; 
PP UNKNOWN; 



Generic pointer to procedure 

typedef P_UNKN0WN FunctionPtr(P_PROC) (); 

True/False values 

Enuml 6 (BOOLEAN) { 

FALSE = 0, 

TRUE = 1, 

False = 0, 

True = 1, 

false = 0, 

true = 1 



cs 



♦define Abs(v) 


((v)<0?(-(v)):(v)) 


tdefine Max(a,b) 


((a)>(b)?(a):(b)) 


tdefine Min(a,b) 


((a)<(b)?(a):(b)) 


tdefine Odd(v) 


((v)fcl) 


tdefine Even(v) 


(!Odd(v)) 


tdefine LowU16(dw) 


( (U16) (U32) (dw) ) 


tdefine HighU16(dw) 


((U16) ((U32) (dw)»16)) 


tdefine LowU8(w) 


((U8)(w)) 


tdefine HighU8(w) 


((U8)((U16)(w)»8)) 


tdefine MakeU16(lb,hb) 


(((Ul6)(hb)«8)|(Ul6) (lb)) 


tdefine MakeU32(lw,hw) 


(((U32) (hw)«16) | (U32) (lw) ) 


tdefine FlagOn(f,v) 


(! FlagOff (f,v)) 


tdefine FlagOff (f,v) 


(!((v)&(f))) 


tdefine FlagSet(f,v) 


((v)|(f)) 


tdefine FlagClr(f,v) 


((v)&(~(f))) 


tdefine OutRange ( v, 1 , h) 


((v)<(l)||(v)>(h)) 


tdefine InRange (v, 1, h) 


((v)>=(l)&&(v)<=(h)) 


tdefine SizeOf (t) 


( (SIZEOF) sizeof(t)) 
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Commonly Used Class Manager Types 3 

A variable of type OBJECT identifies an object. The type UID is interchangeable with OBJECT. 
A variable of type TAG identifies one of the following: 

♦ Tag 

♦ Message 

♦ Error status (values less than 0) 

♦ Warning status (values greater than or equal to 0) 

Well-known UID Structure 

A UID is constructed as: 



♦ 


Version: 


7 bits 


♦ 


Admin: 


20 or 19 bits 


♦ 


Scope: 


1 or 2 bits 


♦ 


Layout: 





00000000001111111111222222222233 
01234567890123456789012345678901 

Name : | Ver | | Admin+Scope 

Size: 1| 7 | 3 | 20+1 or 19+2 

typedef PJJNKNOWN UID, * P_UID; 

typedef UID OBJECT, * P_OBJECT, ** PP_OBJECT; 

Well-known UID Macros 

Create a well-known UID 

#define MakeWKN (admin, version, scope) \ 

((UID) ((U32) (0x7F& (version) )«24 | (U32) (admin) «l+(scope&l) | scope)) 

Create a well-known UID 

♦define MakeGlobalWKN (admin, version) MakeWKN (admin, version, wknGlobal) 

Create a process-global well-known UID 

♦define MakeProcessGlobalWKN (admin, version) \ 
MakeWKN (admin, version, wknProcessGlobal) 

Create a private well-known UID 

#def ine MakePrivateWKN (admin, version) MakeWKN (admin, version, wknPrivate) 

Extract the admin number plus the scope information 

♦define WKNValue (wkn) (0xlFFFFF&(U32)wkn) 

Extract the admin number 

♦define WKNAdmin (wkn) (WKNValue (wkn) »1+ ( (U32) wkn&l) ) 

Extract the version number 

♦define WKNVer (wkn) ( (U32) (wkn)»24) 
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Extract the scope 

#define WKNScope (wkn) ( (U32) (wkn) &- ( (U32) (wkn) 61) &3) 

Magic constants 

#define wknGlobal 
#define wknProcessGlobal 1 
fdefine wknPrivate 3 

Tag Structure 

Tags are created using a well-known Administered value and a tag number in the range 0-255. 



♦ X: 1 bit. for tag or Warning Status; 1 for an Error Status. 


♦ TagNum: 8 bits 


♦ Flags: 2 bits 


♦ Admin: 


20 or 19 bits 


♦ Scope: '. 


I or 2 bits 


♦ Layout: 






00000000001111111111222222222233 
01234567890123456789012345678901 


Name : 


X| tagNum|F| Admin+Scope 


Size: 


1| 8 |2 | 20+1 or 19+2 


typedef S32 
typedef S32 


TAG,* * P_TAG; // Tags are alw< 
STATUS, * P_STATUS; 



Tag Macros 

Create a tag 

fdefine MakeTag (wkn, tagNum) ( ( (TAG) (tagNum) fcOxFF) «23 | WKNValue (wkn) 

Create a tag with flags 

#define MakeTagWithFlags(wkn,i,f) (MakeTag (wkn, i) | ( (U32) (f) &3)«21) 

Extract the tag num 

#define TagNum (tag) ( (U32) (tag)«l»24) 
#define Tag (tag) TagNum (tag) 

Extract the tag num and flags together 

tdefine TagAndFlags (tag) ( (U32) (tag)«l»22) 

Extract only the tag flags 

#define TagFlags (tag) (TagAndFlags (tag) &3) 

Extract the tag admin 

#define TagAdmin (tag) WKNAdmin (tag) 
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Status Macros 3 



u 

Create an error status 

♦define MakeStatus (wkn, sts) ( (STATUS) (0x80000000 |MakeTag(wkn, sts) ) ) 

Create a warning status 

♦define MakeWarning (wkn, sts) ( (STATUS) MakeTag (wkn, sts) ) 

Extract the status num from a STATUS 

♦define Sts (sts) Tag (sts) 



Debugging Macros 



♦define StsRet(se,s) if (((s) = StsWarn(se) ) < stsOK) return s; else 

♦define StsJmp(se,s,x) if (((s) = StsWarn(se)) < stsOK) goto x; else 

♦define StsOK (se,s) (((s) = StsWarn(se)) >= stsOK) 

♦define StsFailed(se,s) (((s) = StsWarn(se)) < stsOK) 

♦define StsChk(se,s) (((s) = (se) ) < stsOK) 



Status Printing Macros 



StsWarn 

Prints status warning message. 
Returns nothing. 

♦if defined DEBUG | | defined CLSMGR_COMPILE 

♦define StsWarn (se) StsWarning(se, FILE , LINE ) 

♦else // if not DEBUG 
♦define StsWarn (se) (se) 

♦endif // DEBUG 



Comments When DEBUG is defined during compilation, the StsWarn macro prints a status warning message if the 

status is less than stsOK (an error). When DEBUG is not defined during compilation, StsWarn simply 
evaluates its expression. 

See Afs© StsPrint 



StsPrint 

Prints status warning message. 
Returns nothing. 

♦if defined DEBUG | | defined CLSMGR_COMPILE 

♦define StsPrint (s) StatusWarning(s, FILE , LINE ) 

♦else //if not DEBUG 
♦define StsPrint (s) 
♦endif // DEBUG 

Comments When DEBUG is defined during compilation, the StsPrint macro prints a status warning message 

regardless of the value of the status. When DEBUG is not defined during compilation, StsPrint does 
nothing. 

See Also StsWarn 
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Status Values 



// Next up: 11 

Classes used to create generic status values (see uid.h) 



tdefine 


clsGO 


MakeWKN (14 , 1, wknGlobal) 


♦define 


clsOS 


MakeWKN(16, 1, wknGlobal) 


#define 


clsGOMath 


MakeWKN (162, 1, wknGlobal) 


Values 

tdefine 


stsBadParam 


MakeStatus (clsGO, 


1) 


tdefine 


stsNoMatch 


MakeStatus (clsGO, 


2) 


tdefine 


stsEndOfData 


MakeStatus (clsGO, 


3) 


tdefine 


stsFailed 


MakeStatus (clsGO, 


4) 


tdefine 


stsTimeOut 


MakeStatus (clsGO, 


5) 


tdefine 


stsRequestNotSupported 


MakeStatus (clsGO, 


6) 


tdefine 


stsReadOnly 


MakeStatus (clsGO, 


7) 


tdefine 


stsIncompatibleVersion 


MakeStatus (clsGO, 


8) 


tdefine 


stsNot Yet Implemented 


MakeStatus (clsGO, 


9) 


tdefine 


stsOutOfMem 


MakeStatus (clsGO, 


10) 



Non-Error Status Values 



// Next up: 4 

tdefine stsOK 

tdefine stsRequestDenied 

tdefine stsRequestForward 

tdefine stsTruncatedData 



MakeWarning(0, 0) 

MakeWarning (clsGO, 1) 

MakeWaming (clsGO, 2) 

MakeWarning (clsGO, 3) 



// also stsMessagelgnored 



GO Math Support 



Conceptually these declarations should be in gomath.h. They are defined here instead to ease the load 
on the compiler symbol tables. 



typedef S32 
typedef FIXED* 
FIXED PASCAL 



FIXED; 

P_FIXED; 

FxMakeFixed(S16 whole, U16 f rac) ; 
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MAIN.H 



Prototype for main(). 

tifndef MAIN_INCLUDED 
#define MAINJENCLUDED 
#ifndef GO_INCLUDED 

#include <go.h> 
tendif 



^Standard main() 

Function Prototype U32 CDECL main(S32 argc, CHAR* argv[], U32 instance); 
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UID.H 



This contains well-known uids for PenPoint. 

tifndef UID_INCLUDED 
#define UID INCLUDED 



Available for Testing (wknGlobals) 



♦define 
tdefine 
#define 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



wknGDTa 
wknGDTb 
wknGDTc 
wknGDTd 
wknGDTe 
wknGDTf 
wknGDTg 
wknGDTh 
wknGDTi 
wknGDTj 
wknGDTk 



MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 
MakeWKN 



(3,l,wknGlobal) 

(4,l,wknGlobal) 

(5,l,wknGlobal) 

(6,l,wknGlobal) 

(7,l,wknGlobal) 

(8,l,wknGlobal) 

(9,l,wknGlobal) 

(32,l,wknGlobal) 

(45,l,wknGlobal) 

(47,l,wknGlobal) 

(73,l,wknGlobal) 



Available for Testing (wknProcessGlobals) 



tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



wknLDTa 
wknLDTb 
wknLDTc 
wknLDTd 
wknLDTe 
wknLDTf 
wknLDTg 



MakeWKN (3, 
MakeWKN (4, 
MakeWKN (5, 
MakeWKN (6, 
MakeWKN (7, 
MakeWKN (8, 
MakeWKN (9, 



1 , wknProces sGlobal ) 
l,wknProcessGlobal) 
1, wknProces sGlobal) 
1, wknProcessGlobal) 
l,wknProcessGlobal) 
1, wknProcessGlobal) 
1, wknProcessGlobal) 



Well-known Objects 



tdefine 


objNull 


MakeWKN 


tdefine 


clsProcess 


MakeWKN 


tdefine 


clsObject 


MakeWKN 


tdefine 


clsClass 


MakeWKN 


tdefine 


theProcess 


MakeWKN 


tdefine 


clsGO 


MakeWKN 


tdefine 


clsOS 


MakeWKN 


tdefine 


clsGOMath 


MakeWKN 


tdefine 


clsMisc 


MakeWKN 


tdefine 


clsSystem 


MakeWKN 


tdefine 


theSystem 


MakeWKN 


tdefine 


clsInitTask 


MakeWKN 


tdefine 


theSystemlnitTask 


MakeWKN 


tdefine theThirdPartylnitTask 


MakeWKN 


tdefine 


theBookshelf 


MakeWKN 


tdefine 


theSystemResFile 


MakeWKN 


tdefine 


theMILResFile 


MakeWKN 


tdefine 


theDesktop 


MakeWKN 



(0,0,0) 

(0,l,wknGlobal) 

(l,l,wknGlobal) 

(2,l,wknGlobal) 

(0,1, wknProcessGlobal) 

(14,l,wknGlobal) 

(16,l,wknGlobal) 

(162,l,wknGlobal) 

(112,l,wknGlobal) 

(174,l,wknGlobal) 

(174,l,wknGlobal) 

(433,l,wknGlobal) 
(431,l,wknGlobal) 
(432,l,wknGlobal) 
(127,l,wknGlobal) 
(172,l,wknGlobal) 
(414,l,wknGlobal) 

(127,l,wknGlobal) // obsolete 
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Application Framework 



tdefine clsApp 


MakeWKN 


tdefine clsAppMgr 


MakeWKN 


tdefine clsAppDir 


MakeWKN 


tdefine clsAppWin 


MakeWKN 


tdefine clsAppWinlcon 


MakeWKN 


tdefine clsContainerApp 


MakeWKN 


tdefine clsRootContainerApp 


MakeWKN 


tdefine clsList 


MakeWKN 


tdefine clsView 


MakeWKN 


tdefine clsEmbeddedWin 


MakeWKN 


tdefine clsIconWin 


MakeWKN 


tdefine clsGotoButton 


MakeWKN 


tdefine clsPowerButtonUI 


MakeWKN 


tdefine clsCorkBoardWin 


MakeWKN 


tdefine clsMemoryCop 


MakeWKN 


tdefine theMemoryCop 


MakeWKN 


Bookshelf 





tdefine clsBSApp 
tdefine clsBSMainWin 
tdefine clsBSWin 
tdefine clsBSZTWin 



(13,1, wknGlobal) 
(69,l,wknGlobal) 
(157,1, wknGlobal) 
(159,l,wknGlobal) 
(153,1, wknGlobal) 
(121,1, wknGlobal) 
(218,1, wknGlobal) 
(10,l,wknGlobal) 
(15,1, wknGlobal) 
(11,1, wknGlobal) 
(80,1, wknGlobal) 
(183,l,wknGlobal) 
(458,l,wknGlobal) 
(148,1, wknGlobal) 
(443,1, wknGlobal) 
(457,l,wknGlobal) 



MakeWKN (168, l,wknGlobal) // PenPoint internal 

MakeWKN (1 67, l,wknGlobal) // PenPoint internal 

MakeWKN (359, 1, wknGlobal) // PenPoint internal 

MakeWKN (1 64, l,wknGlobal) // PenPoint internal 



Notebook 








tdefine clsNBApp 


MakeWKN (44, 1, wknGlobal) 






tdefine clsNBToc 


MakeWKN ( 13 6 , 1 , wknGlobal ) 






tdefine clsSectApp 


MakeWKN (145,1, wknGlobal ) 






tdefine clsNBFrame 


MakeWKN (92,1, wknGlobal ) 


// PenPoint 


internal 


tdefine clsBookmark 


MakeWKN ( 1 8 4 , 1 , wknGlobal ) 


// PenPoint 


internal 


tdefine clsPageControl 


MakeWKN ( 1 5 6 , 1 , wknGlobal ) 


// PenPoint 


internal 


tdefine clsPageWin 


MakeWKN ( 1 61 , 1 , wknGlobal ) 


// PenPoint 


internal 


tdefine clsSectMenu 


MakeWKN (226, 1, wknGlobal) 


// PenPoint 


internal 


tdefine clsNBSApp 


MakeWKN (284, 1, wknGlobal) 


// PenPoint 


internal 


tdefine clsNBSMenu 


MakeWKN ( 83 , 1 , wknGlobal ) 


// PenPoint 


internal 



Input 



tdefine thelnputManager 
tdefine clslnput 
tdefine thePen 
tdefine clsPen 
tdefine theKeyboard 
tdefine clsKey 
tdefine clsAcetateAlign 



MakeWKN (17,1, wknGlobal ) 
MakeWKN ( 1 7 , 1 , wknGlobal ) 
MakeWKN ( 1 8 , 1 , wknGlobal ) 
MakeWKN (18, 1, wknGlobal) 
MakeWKN (19, 1, wknGlobal) 
MakeWKN (19,1, wknGlobal ) 
MakeWKN ( 90 , 1 , wknGlobal ) 



Hwx Tools 



tdefine clsScribble 
tdefine clsSPaper 
tdefine clsIP 
tdefine clsIPButton 
tdefine clsGWin 
tdefine clsField 



MakeWKN (2 , 1 , wknGlobal ) 
MakeWKN (21,1, wknGlobal ) 
MakeWKN (77,1, wknGlobal ) 
MakeWKN (79, 1, wknGlobal) 
MakeWKN (219,1, wknGlobal ) 
MakeWKN (22 , 1 , wknGlobal) 



Pjr Virtual Keyboard 



#define clsKeyCap 
tdefine clsKeyboard 
tdefine theVirtualKeyboard 
tdefine clsVKeyApp 
tdefine clsVKeyWin 



MakeWKN (96,1, wknGlobal ) 
MakeWKN (97,1, wknGlobal) 
MakeWKN (199,1, wknGlobal ) 
MakeWKN (198,1, wknGlobal ) 
MakeWKN (132, 1, wknGlobal) 
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P^ The System Log Application 



♦define theSystemLog 
tdefine clsSystemLog 
tdefine clsSysLogApp 
tdefine clsTextOut 



MakeWKN ( 4 6 , 1 , wknGlobal ) 
MakeWKN ( 7 8 , 1 , wknGlobal ) 
MakeWKN (330, 1, wknGlobal) 
MakeWKN ( 3 9 , 1 , wknGlobal ) 



// PenPoint internal 



Quick Help 



tdefine theQuickHelpManager 

tifndef NO_GRANDFATHER 

tdefine theQuickHelp 

tendif 

tdefine clsQuickHelp 

tdefine clsQHWin 



MakeWKN (85, 1, wknGlobal) 

theQuickHelpManager 

MakeWKN (85, 1, wknGlobal) 
MakeWKN (154, 1, wknGlobal) 



Printing 



tdefine clsPrFrame 
tdefine clsPrint 
tdefine thePrintManager 
tdefine clsPrMgr 
tdefine clsPrintManager 
tdefine clsPrMargin 
tdefine clsPrLayout 



MakeWKN (279, 
MakeWKN (280, 
MakeWKN (281, 
MakeWKN (281, 
MakeWKN (379, 
MakeWKN (283, 
MakeWKN (3 97, 



1, wknGlobal) 
1, wknGlobal) 
1, wknGlobal) 
1, wknGlobal) 
1, wknGlobal) 
1, wknGlobal) 
1, wknGlobal) 



Battery 



tdefine theBatteries 
tdefine theBattery 



MakeWKN (354, 1, wknGlobal) 
MakeWKN (282 , 1 , wknGlobal) 



Ppr HWX 



tdefine 


clsXlate 


MakeWKN 


tdefine 


clsXtract 


MakeWKN 


tdefine 


clsXText 


MakeWKN 


tdefine 


clsXWord 


MakeWKN 


tdefine 


clsXGesture 


MakeWKN 


tdefine 


clsXNumber 


MakeWKN 


tdefine 


clsXGeometric 


MakeWKN 


tdefine theHWXProtos 


MakeWKN 


tdefine 


clsHWXProto 


MakeWKN 


tdefine 


clsXTeach 


MakeWKN 


tdefine 


clsXShape 


MakeWKN 


tdefine 


clsGOShape 


MakeWKN 


tdefine 


clsGOShapeService 


MakeWKN 


tdefine 


clsCTShape 


MakeWKN 


tdefine 


clsCTShapeService 


MakeWKN 



(23,1, wknGlobal) 
(98,1, wknGlobal) 
(99,1, wknGlobal) 
(101,1, wknGlobal) 
(102,1, wknGlobal) 
(103,1, wknGlobal) 
(104,1, wknGlobal) 
(105,1, wknGlobal) 
(105,1, wknGlobal) 
(100,1, wknGlobal) 
(251,1, wknGlobal) 
(252,1, wknGlobal) 
(253,1, wknGlobal) 
(254,1, wknGlobal) 
(255,1, wknGlobal) 
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File System, etc 



♦define theFileSystem 


MakeWKN 


tdefine clsFileSystem 


MakeWKN 


♦define clsDirHandle 


MakeWKN 


tdefine clsFileHandle 


MakeWKN 


tdefine theVolSearcher 


MakeWKN 


tdefine clsVolSearch 


MakeWKN 


tdefine clsVolume 


MakeWKN 


tdefine clsVolRAM 


MakeWKN 


tdefine clsVolMSDisk 


MakeWKN 


tdefine clsVolTOPS 


MakeWKN 


tdefine theBlockDeviceManager 


MakeWKN 


tdefine clsBlockDeviceManager 


MakeWKN 


tdefine clsBlockDevice 


MakeWKN 


tdefine theSCSIDriver 


MakeWKN 


tdefine clsSCSI 


MakeWKN 


tdefine clsSCSISenseCodes 


MakeWKN 


tdefine clsATBiosDisk 


MakeWKN 


tdefine clsResFile 


MakeWKN 


tdefine clsResList 


MakeWKN 


tdefine theProcessResList 


MakeWKN 


tdefine theBootVolume 


MakeWKN 


tdefine theSelectedVolume 


MakeWKN 


tdefine theWorkingDir 


MakeWKN 


tdefine clsFileHandleAppendOnly 


MakeWKN 



(62,l,wknGlobal) 
(62,l,wknGlobal) 
(28,1, wknGlobal) 
(29,1, wknGlobal) 
(143,1, wknGlobal) 
(143,1, wknGlobal) 
(30,l,wknGlobal) 
(49,1, wknGlobal) 
(61,1, wknGlobal) 
(120,1, wknGlobal) 
(412,l,wknGlobal) 
(412,1, wknGlobal) 
(413,1, wknGlobal) 
(31,l,wknGlobal) 
(31,1, wknGlobal) 
(299,1, wknGlobal) 
(302,1, wknGlobal) 
(285,1, wknGlobal) 
(286,1, wknGlobal) 
(12 , 1 , wknProcessGlobal ) 
(138,1, wknGlobal) 
(125,1, wknGlobal) 
(10,1, wknProcessGlobal) 
(494,l,wknGlobal) 



Disk Viewer 



tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



clsDiskViewWin MakeWKN (384, l,wknGlobal) 

clsDisklnstaller MakeWKN (385, l,wknGlobal) 

clsDVBookshelf MakeWKN (188, l,wknGlobal) 

clsDiskViewApp MakeWKN (243, l,wknGlobal) // Penpoint internal 

clsDVBrowBar MakeWKN ( 141, l,wknGlobal) // PenPoint internal 

clsDVTabButton MakeWKN (134, l,wknGlobal) // PenPoint internal 

clsDVIcon MakeWKN (137, l,wknGlobal) // PenPoint internal 

clsDVForward MakeWKN (140,1, wknGlobal) // PenPoint internal 

clsDVBrowser MakeWKN (171, l,wknGlobal) // PenPoint internal 

clsDVIconWin MakeWKN (1 44, l,wknGlobal) // PenPoint internal 

MakeWKN (128,1, wknGlobal ) 



tdefine clsDynamicTableMgr 



Configuration Notebook 



tdefine clsConfigurationApp 
tdefine theConfigurationBook 



MakeWKN (197, 1, wknGlobal) 
MakeWKN (206, 1, wknGlobal) 



Settings NB 



tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



clsSettingsNB MakeWKN (239, 1, wknGlobal) 

clsSettingsNBAppWin MakeWKN (150, 1, wknGlobal) 

clsInstallUISheet MakeWKN (117,1, wknGlobal) 

els Inst allUICard MakeWKN (256, 1, wknGlobal) 

clsInstallUIButton MakeWKN (209,1, wknGlobal) 

clsInstallUIBrowser MakeWKN (387, 1, wknGlobal) 

clsQuicklnstallUI MakeWKN (142, 1, wknGlobal) 



// PenPoint internal 

// PenPoint internal 

// PenPoint internal 

// PenPoint internal 

// PenPoint internal 
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ff? Install Manager classes 



♦define clsInstallMgr MakeWKN(249,l,wknGlobal) 

♦define clsCodelnstallMgr MakeWKN (193,1, wknGlobal) 

♦define clsAppInstallMgr MakeWKN (260,1, wknGlobal) 

#define clsFontlnstallMgr MakeWKN (268,1, wknGlobal) 

♦define clsHWXProtoInstallMgr MakeWKN(177,l,wknGlobal) 

♦define clsPDictlnstallMgr MakeWKN (428,1, wknGlobal) 

♦define clsUpgradeApp MakeWKN (291, 1, wknGlobal) 

#define clsUpgradeAppMonitor MakeWKN (292,1, wknGlobal) 



Install Manager well-known instances 



♦define thelnstallManagers MakeWKN(236, l,wknGlobal) 

♦define thelnstalledHWXProtos MakeWKN(250,l,wknGlobal) 

♦define thelnstalledGestures MakeWKN (409, 1, wknGlobal) 

#define thelnstalledApps MakeWKN(208,l,wknGlobal) 

#define thelnstalledPDicts MakeWKN(331,l,wknGlobal) 

#define thelnstalledPrefs MakeWKN (332, 1, wknGlobal) 

♦define thelnstalledServices MakeWKN (288,1, wknGlobal) 

♦define thelnstalledFonts MakeWKN(211,l,wknGlobal) 



Application Monitor 

#define clsAppMonitor 



MakeWKN (278,1, wknGlobal ) 



P^ Auxilliary Notebook Manager 



♦define clsAuxNotebookMgr 
♦define theAuxNotebookMgr 
tdefine clsIniFileHandler 
♦define clsStationeryMenu 
♦define theStationeryMenu 



MakeWKN (314,1, wknGlobal) 
MakeWKN (313, 1, wknGlobal) 
MakeWKN (398, 1, wknGlobal) 
MakeWKN ( 93 , 1 , wknGlobal) 
MakeWKN ( 93 , 1 , wknGlobal) 



// PenPoint internal 
// PenPoint internal 



P^ Auxilliary Notebooks 



♦define clsHelpNB 
♦define clsStationeryNB 
♦define clsStationeryBrowWin 
♦define clsInboxNB 
♦define clsOutboxNB 



MakeWKN (335, 1, wknGlobal) 
MakeWKN (333, 1, wknGlobal) 
MakeWKN ( 1 60 , 1 , wknGlobal ) 
MakeWKN (388, 1, wknGlobal) 
MakeWKN (389, 1, wknGlobal) 



// PenPoint internal 



Pfr Accessory Pallette 



♦define clsAccessoryPallette 
♦define clsAccessoryWin 
♦define clsAccessoryAppWin 



MakeWKN (391, 1, wknGlobal) 
MakeWKN (396,1, wknGlobal ) 
MakeWKN (440,1, wknGlobal ) 



Service Classes 



♦define clsService MakeWKN (349, 1, wknGlobal) 

♦define clsMILService MakeWKN (434,1, wknGlobal) 

♦define clsServiceMgr MakeWKN (350, 1, wknGlobal) 

♦define clsServicelnstallMgr MakeWKN (240, 1, wknGlobal) 

♦define clsPrintSpoolSvc MakeWKN (363,1, wknGlobal) 

♦define clsSendableService MakeWKN (169, 1, wknGlobal) 

♦define clsHWXEngineService MakeWKN (180, 1, wknGlobal) 

♦define clsOpenServiceObject MakeWKN (17 6,1, wknGlobal) 

♦define clsMILConflictGroupMgr MakeWKN (415, 1, wknGlobal) 

♦define theServiceResList MakeWKN (189, 1, wknGlobal) 

♦define theServiceManagers MakeWKN (237, 1, wknGlobal) 
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Service Managers 



#define 
tdefine 
#define 
#define 
tdefine 
tdefine 
♦define 
#define 
tdefine 
tdefine 
tdefine 
♦define 
tdefine 



theMILDevices 

theParallelDevices 

theAppleTalkDevices 

theSerialDevices 

thePrinterDevices 

thePrinters 

theSendableServices 

theTransportHandlers 

theLinkHandlers 

theHWXEngines 

theModems 



MakeWKN (383,1, wknGlobal ) 
MakeWKN(152, l,wknGlobal) 
MakeWKN (30 8,1, wknGlobal) 
MakeWKN ( 3 9 , 1 , wknGlobal ) 
MakeWKN (310,1, wknGlobal ) 
MakeWKN (210,1, wknGlobal) 
MakeWKN (24, 1, wknGlobal) 
MakeWKN (25, 1, wknGlobal) 
MakeWKN (26, 1, wknGlobal) 
MakeWKN (175,1, wknGlobal) 



MakeWKN ( 1 94 , 1 , wknGlobal ) 
theHighSpeedPacketHandlers MakeWKN (439, 1, wknGlobal) 
theFaxIOServices MakeWKN (217, 1, wknGlobal) 



Service Sample Code 



tdefine clsBasicService 
tdefine clsTestService 
tdefine clsTestOpenObject 
tdefine clsTestMILService 



MakeWKN (4 60,1, wknGlobal) 
MakeWKN ( 1 8 6 , 1 , wknGlobal ) 
MakeWKN (207,1, wknGlobal ) 
MakeWKN (459,1, wknGlobal ) 



Modem Component 



tdefine clsModem 



MakeWKN (151,1, wknGlobal ) 



Parallel Port Component 



tdefine clsParallelPort 



MakeWKN (196,1, wknGlobal ) 



Text Component 



tdefine clsText 
tdefine clsTextView 
tdefine clsTextChar 
tdefine clsTextMarkStore 
tdefine clsTextBlock 
tdefine clsTextlP 



MakeWKN (35,1, wknGlobal ) 

MakeWKN (36,1, wknGlobal ) 

MakeWKN (33,1, wknGlobal) 

MakeWKN ( 3 4 , 1 , wknGlobal ) 

clsText 

MakeWKN (355, 1, wknGlobal) 



Undo Manager 



tdefine clsUndo 

tdefine theUndoCoordinater 

tdefine theUndoManager 



MakeWKN (235, 1, wknGlobal) 
MakeWKN (126, 1, wknGlobal) 
MakeWKN (11, l,wknProcessGlobal) 



Windows and Graphics 



tdefine clsDrwCtx 


MakeWKN 


tdefine clsSysDrwCtx 


MakeWKN 


tdefine clsPixDev 


MakeWKN 


tdefine clsImgDev 


MakeWKN 


tdefine clsWinDev 


MakeWKN 


tdefine clsWin 


MakeWKN 


tdefine theScreen 


MakeWKN 


tdefine theRootWindow 


MakeWKN 


tdefine clsBitmap 


MakeWKN 


tdefine clsPicSeg 


MakeWKN 


tdefine clsTiff 


MakeWKN 



(37,1, wknGlobal) 
(38,1, wknGlobal) 
(40,1, wknGlobal) 
(41,1, wknGlobal) 
(42,1, wknGlobal) 
(43,1, wknGlobal) 
(50,1, wknGlobal) 
(67,1, wknGlobal) 
(378,1, wknGlobal) 
(82,1, wknGlobal) 
(66,1, wknGlobal) 



ff> Layout and Tracking 



#define clsBorder 
#define clsLayout 
♦define clsTableLayout 
tdefine clsCustomLayout 
tdefine clsTrack 



MakeWKN (135,1, wknGlobal ) 
MakeWKN(53, l,wknGlobal) 
MakeWKN (55,1, wknGlobal ) 
MakeWKN (54,1, wknGlobal) 
MakeWKN (12,1, wknGlobal) 
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Vf> Toolkit 



♦define 


clsImageWin 


MakeWKN ( 


♦define 


clsFrame 


MakeWKN ( 


tdefine 


clsFrameBorder 


MakeWKN ( 


tdefine 


clsScrollWin 


MakeWKN ( 


tdefine 


clsScrollWinlnnerWin 


MakeWKN ( 


tdefine 


clsControl 


MakeWKN ( 


tdefine 


clsCloseBox 


MakeWKN ( 


tdefine 


clsGrabBox 


MakeWKN ( 


tdefine 


clsScrollbar 


MakeWKN ( 


tdefine 


clsLabel 


MakeWKN ( 


tdefine 


clsButton 


MakeWKN ( 


tdefine 


clsMenuButton 


MakeWKN ( 


tdefine 


clsContentsButton 


MakeWKN ( 


tdefine 


clslcon 


MakeWKN ( 


tdefine 


clsIconToggle 


MakeWKN ( 


tdefine clsMoveCopylcon 


MakeWKN ( 


tdefine 


clsTitleBar 


MakeWKN ( 


tdefine 


clsTkTable 


MakeWKN ( 


tdefine clsOptionTable 


MakeWKN ( 


tdefine 


clsContentsTable 


MakeWKN ( 


tdefine 


clsMenu 


MakeWKN ( 


tdefine 


els Shadow 


MakeWKN ( 


tdefine clsPageNum 


MakeWKN ( 


tdefine 


clsTabBar 


MakeWKN ( 


tdefine 


clsTabButton 


MakeWKN ( 


tdefine 


clsOption 


MakeWKN ( 


tdefine clsOptionBook 


MakeWKN ( 


tdefine 


clsCommandBar 


MakeWKN ( 


tdefine 


clsCounter 


MakeWKN ( 



(182,1, wknGlobal) 
(56,1, wknGlobal) 
(337,1, wknGlobal) 
(155,1, wknGlobal) 
(338,1, wknGlobal) 
(48,1, wknGlobal) 
(71,1, wknGlobal) 
(266,1, wknGlobal) 
(58,1, wknGlobal) 
(75,1, wknGlobal) 
(52,1, wknGlobal) 
(72,1, wknGlobal) 
(192,1, wknGlobal) 
(360,1, wknGlobal) 
(124,1, wknGlobal) 
(361,1, wknGlobal) 
(163,1, wknGlobal) 
(68,1, wknGlobal) 
(298,1, wknGlobal) 
(190,1, wknGlobal) 
(57,1, wknGlobal) 
(181,1, wknGlobal) 
(74,1, wknGlobal) 
(70,1, wknGlobal) 
(60,1, wknGlobal) 
(224,1, wknGlobal) 
(191,1, wknGlobal) 
(228,1, wknGlobal) 
(110,1, wknGlobal) 



Pp^ TK np 



tdefine clsChoice 


MakeWKN 


tdefine clsPopupChoice 


MakeWKN 


tdefine clsToggleTable 


MakeWKN 


tdefine clsIconChoice 


MakeWKN 


tdefine clsIconTable 


MakeWKN 


tdefine clsListBox 


MakeWKN 


tdefine clsListBoxDisplay 


MakeWKN 


tdefine clsManager 


MakeWKN 


tdefine clsChoiceMgr 


MakeWKN 


tdefine clsSelChoiceMgr 


MakeWKN 


tdefine clsTextField 


MakeWKN 


tdefine clsIntegerField 


MakeWKN 


tdefine clsFixedField 


MakeWKN 


tdefine clsDateField 


MakeWKN 


tdefine theBusyManager 


MakeWKN 


tdefine clsBusy 


MakeWKN 


tdefine clsModalFilter 


MakeWKN 


tdefine clsNote 


MakeWKN 


tdefine clsNoteBorder 


MakeWKN 


tdefine clsStringListBox 


MakeWKN 


tdefine clsFontListBox 


MakeWKN 


tdefine clsProgressBar 


MakeWKN 



(59,1, wknGlobal) 
(297,1, wknGlobal) 
(76,1, wknGlobal) 
(320,1, wknGlobal) 
(321,1, wknGlobal) 
(94,1, wknGlobal) 
(275,1, wknGlobal) 
(244,1, wknGlobal) 
(241,1, wknGlobal) 
(246,1, wknGlobal) 
(95,1, wknGlobal) 
(294,1, wknGlobal) 
(295,1, wknGlobal) 
(296,1, wknGlobal) 
(242,1, wknGlobal) 
(242,1, wknGlobal) 
(311,1, wknGlobal) 
(312,1, wknGlobal) 
(195,1, wknGlobal) 
(343,1, wknGlobal) 
(344,1, wknGlobal) 
(187,1, wknGlobal) 



70 PENPOINT API REFERENCE 

Part 1 / Class Manager 

Import/Export 

tdefine els Import 
tdefine clsExport 
#define theExportManager 
tdefine clsExportManager 



MakeWKN (289,1, wknGlobal) 
MakeWKN (290,1, wknGlobal) 
MakeWKN(84, l,wknGlobal) 
MakeWKN (106, 1, wknGlobal) 



Browser 



♦define 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



clsBrowser 

clsBrowWin 

clsBrowApp 

clsBrowFrame 

clsBrowMenu 

clsBrowExport 

clsBrowImport 

clsBrowRename 

clsLuke 



MakeWKN (87,1, wknGlobal ) 
MakeWKN (I7S , 1 , wknGlobal ) 
MakeWKN (179, 1, wknGlobal) 
MakeWKN(221, 1, wknGlobal) 
MakeWKN (261,1, wknGlobal) 
MakeWKN ( 3 , 1 , wknGlobal ) 
MakeWKN (303, 1, wknGlobal) 
MakeWKN (326, 1, wknGlobal) 
MakeWKN (222, 1, wknGlobal) 



//• PenPoint internal 



Communications 



tdefine 


clsStream 


MakeWKN 


tdefine 


clsSccSio 


MakeWKN 


tdefine 


clsLSio 


MakeWKN 


tdefine 


clsSioUI 


MakeWKN 


tdefine 


clsFLAP 


MakeWKN 


tdefine 


clsALAPSerial 


MakeWKN 


tdefine 


clsIconCache 


MakeWKN 


tdefine 


thelconCache 


MakeWKN 


tdefine 


clsWSio 


MakeWKN 


tdefine 


clsSioTest 


MakeWKN 



(64,1, wknGlobal) 
(351,1, wknGlobal) 
(381,1, wknGlobal) 
(122,1, wknGlobal) 
(392,1, wknGlobal) 
(393,1, wknGlobal) 
(107,1, wknGlobal) 
(442,1, wknGlobal) 
(123,1, wknGlobal) 
(158,1, wknGlobal) 



Fax Send/Receive Page Service 

tdefine clsFaxIOSvc MakeWKN (271, 1, wknGlobal) 



Search and Replace 



tdefine clsSR 
tdefine clsSF 
tdefine theSearchManager 



MakeWKN (293, 1, wknGlobal) 

MakeWKN (382,1, wknGlobal) // search frame 

MakeWKN (27, 1, wknGlobal) 



Traverse 



tdefine clsMark 



MakeWKN (257, 1, wknGlobal) 



Textedit Application 



tdefine clsTexteditApp 
tdefine clsTexteditAppMonitor 



MakeWKN (356, 1, wknGlobal) 
MakeWKN (357,1, wknGlobal) 



Networking 



tdefine clsTransport MakeWKN 

tdefine clsLink MakeWKN 

tdefine clsHighSpeedPacket MakeWKN 

tdefine clsALAPHighSpeed MakeWKN 

tdefine clsATP MakeWKN 

tdefine clsATPHandle MakeWKN 

tdefine theATPDriver MakeWKN 

tdefine clsSoftTalk MakeWKN 



(88,1, wknGlobal) 
(394,1, wknGlobal) 
(438,1, wknGlobal) 
(417,1, wknGlobal) 
(89,1, wknGlobal) 
(318,1, wknGlobal) 
(319,1, wknGlobal) 
(119,1, wknGlobal) 
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#define 


theSoftTalkDriver 


MakeWKN 


#define 


clsTopsMounter 


MakeWKN 


#define 


theTopsMounter 


MakeWKN 


#define 


theTopsService 


MakeWKN 


tdefine 


clsTOPS 


MakeWKN 


#define 


theTopsVolumes 


MakeWKN 


tdefine 


theTopsPrinters 


MakeWKN 


tdefine 


theRemoteServices 


MakeWKN 



(86,l,wknGlobal) 

(116,l,wknGlobal) 

(118,l,wknGlobal) 

(345,l,wknGlobal) 

(400,l,wknGlobal) 

(401,l,wknGlobal) 

(402,l,wknGlobal) 

(403,l,wknGlobal) 



Selection and Data Transfer 

#define theSelectionManager 
tdefine clsSelection 
tdefine clsXfer 
#define clsXferList 
#define clsPipe 



MakeWKN (111, l,wknGlobal) 
MakeWKN (111, l,wknGlobal) 
MakeWKN (139, l,wknGlobal) 
MakeWKN ( 322, l,wknGlobal) 
MakeWKN (63, l,wknGlobal) 



// PenPoint internal 



Timer 



tdefine theTimer 
tdefine clsTimer 



MakeWKN (109, l,wknGlobal) 
MakeWKN (109, l,wknGlobal) 



Preferences 



tdefine theSystemPreferences 
tdefine clsPreferences 
tdefine clsPrefApp 
tdefine clsPrefSheet 



MakeWKN (324, l,wknGlobal) 
MakeWKN (323, l,wknGlobal) 
MakeWKN (115, 1, wknGlobal) 
MakeWKN (216,1, wknGlobal ) 



Power Management 



tdefine clsPowerButton 

tdefine thePowerButton 

tdefine clsPowerMgr 

tdefine thePowerMgr 



MakeWKN (348 , 1 , wknGlobal) 
MakeWKN (348,1, wknGlobal) 
MakeWKN (416,1, wknGlobal ) 
MakeWKN (416,1, wknGlobal) 



Send and Address Book Managers 



tdefine clsAddressBook 
tdefine theAddressBookMgr 
tdefine theSendManager 



MakeWKN (346,1, wknGl oba 1 ) 
MakeWKN (342,1, wknGlobal) 
MakeWKN (341,1, wknGlobal) 



Spell Manager 



tdefine theSpellManager 

tdefine clsSpellManager 

tdefine clsSpellField 

tdefine theProcessSpellManager 



MakeWKN (380, 1, wknGlobal) 
MakeWKN (200,1, wknGlobal ) 
MakeWKN (38 6,1, wknGlobal) 
MakeWKN (2, l,wknProcessGlobal) 



Personal Dictionary 



tdefine clsPDict 

tdefine thePersonalDictionary 

tdefine clsPDApp 

tdefine clsPDUI 



MakeWKN (328, 1, wknGlobal) 

MakeWKN (329,1, wknGlobal) 

MakeWKN (336,1, wknGlobal) // obsolete 

MakeWKN (336,1, wknGlobal) // Replaces clsPDApp 
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Printer Drivers 

#define clsPrn 
#define clsBndPrn 
#define clsEpson 
tdefine clsPcl 
#define clsPscript 
#define clsFaxPm 
tdefine clsPrnUI 
tdefine clsRemora 



MakeWKN (201,1, wknGlobal) 
MakeWKN (202,1, wknGlobal) 
MakeWKN(203,l,wknGlobal) 
MakeWKN (204, 1, wknGlobal) 
MakeWKN (205,1, wknGlobal) 
MakeWKN (245, 1, wknGlobal) 
MakeWKN ( 91 , 1 , wknGlobal ) 
MakeWKN (364, 1, wknGlobal) 



Handwriting Customization 



tdefine clsHWCustomFrame MakeWKN (316,1, wknGlobal) 

tdefine clsPlatoHomeWin MakeWKN (347, 1, wknGlobal) 

tdefine clsPlato26Win MakeWKN (334,1, wknGlobal) 

tdefine clsPlato26WinKbd MakeWKN (339, 1, wknGlobal) 

tdefine clsPlatoCustomStat MakeWKN (362, 1, wknGlobal) 

tdefine clsPlatoBox MakeWKN (232,1, wknGlobal) 



Letter & Gesture Practice 

tdefine clsHWLetterFrame MakeWKN (146, 1, wknGlobal) 

tdefine clsHWLetterWin MakeWKN ( 17 0, 1, wknGlobal) 

tdefine clsHWLetterKbd MakeWKN (390,1, wknGlobal) 

tdefine clsHWLetterBkgr MakeWKN (404, 1, wknGlobal) 

tdefine clsHWGestFrame MakeWKN (14 7,1, wknGlobal) 

tdefine clsHWGestWin MakeWKN (410,1, wknGlobal) 

tdefine clsHWGestPracWin MakeWKN (411, 1, wknGlobal) 



Animator 



tdefine clsAnimSPaper 
tdefine clsAnimSysDc 



MakeWKN (234, 1, wknGlobal) 
MakeWKN (81,1, wknGlobal ) 



Inbox / Outbox /Wrapper 



tdefine clsOutboxSectApp MakeWKN (272,1, wknGlobal) 

tdefine clsOBXService MakeWKN (352,1, wknGlobal) 

tdefine clsOBXWin MakeWKN (399,1, wknGlobal) 

tdefine clsIOBXService MakeWKN (353,1, wknGlobal) 

tdefine clsOBXWrapperApp MakeWKN (273, 1, wknGlobal) 

tdefine clsPrintWrapperApp MakeWKN (274, 1, wknGlobal) 

tdefine clsPrnlnstlApp MakeWKN (395,1, wknGlobal) 

tdefine clsINBXSectApp MakeWKN (113,1, wknGlobal) 

tdefine clsINBXService MakeWKN (114,1, wknGlobal) 

tdefine clsINBXWin MakeWKN (133,1, wknGlobal) 

tdefine clsTPSPSvc MakeWKN (12 9,1, wknGlobal) 

tdefine clsTPrnMgr MakeWKN (130, 1, wknGlobal) 

tdefine theTopsPSPManager MakeWKN (131, 1, wknGlobal) 

tdefine clsOBXBrowWin MakeWKN (149, 1, wknGlobal) 

tdefine clsINBOXBrowWin MakeWKN (173, 1, wknGlobal) 

tdefine clsIOBXStatusWin MakeWKN (212, 1, wknGlobal) 

tdefine theOutboxServices MakeWKN (429,1, wknGlobal) 

tdefine thelnboxServices MakeWKN (430,1, wknGlobal) 



Mask App 



♦define clsMaskApp 
♦define clsMaskAppMonitor 



MakeWKN(327,l,wknGlobal) 
MakeWKN (325,1, wknGlobal) 



UID.H 



73 



Clock App 



♦define clsClockApp 
♦define clsClockLabel 
♦define clsClockWin 



MakeWKN(165,l,wknGlobal) 
MakeWKN(220,l,wknGlobal) 
MakeWKN(223, l,wknGlobal) 



Note Icon Window (used in Clock App) 

♦define clsNotelconWin MakeWKN (166, 1, wknGlobal) 



Miscellaneous 



♦define clsString 
♦define clsByteBuf 



MakeWKN(108,l,wknGlobal) 
MakeWKN(185,l,wknGlobal) 



Test Support 

♦define clsTestNB 



MakeWKN(65,l,wknGlobal) 



The MIL 



♦define theMIL 

♦define theMILMachineType 

♦define theMILUnitTag 



MakeWKN(213, 1, wknGlobal) 
MakeWKN(215, 1, wknGlobal) 
MakeWKN(227, 1, wknGlobal) 



MIL device ids, and the classes of the MIL services for these devices. 



♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 



clsMILBaseDevice 
clsMILInitDevice 
clsMILPowerDevice 
clsMILTimerDevice 



MakeWKN(214 
MakeWKN(229 
MakeWKN(230 
MakeWKN(231 



clsMILRealTimeClockDevice MakeWKN 
clsMILInterruptDevice MakeWKN (238 
clsMILScreenDevice MakeWKN (247 
clsMILStylusDevice MakeWKN (248 
clsMILNMIDevice MakeWKN (258 
clsMILSoundDevice MakeWKN (259 
clsMILKeyboardDevice MakeWKN (262 
clsMILAsyncSIODevice MakeWKN (263 
clsMILParallelPortDevice MakeWKN 



clsMILAppleLAPDevice 
clsMILNVMemDevice 
clsMILSCSIDevice 
clsMILFlashDevice 



MakeWKN (265 
MakeWKN (267 
MakeWKN (269 
MakeWKN (270 



clsMILCompressionDevice MakeWKN (276 

clsMILDebugDevice MakeWKN (277 

clsMILBlockDevice MakeWKN (287 

clsMILFDiskDevice MakeWKN (301 

clsMILDisketteDevice MakeWKN (304 

clsMILFlashDiskDevice MakeWKN (305 

clsMILMemoryCardDevice MakeWKN (306 

clsMILHSPacketDevice MakeWKN (435 



, 1 

, 1 

, 1 

, 1 
(233, 

, 1 

, 1 

, 1 

, 1 

r 1 

, 1 

, 1 

(264, 

r 1 

, 1 

r 1 

, 1 

, 1 

, 1 

, 1 

r 1 

r 1 

, 1 

, 1 

r 1 



wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 

1, wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 

1, wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 
wknGlobal) 



These device Ids may be used for temporary testing of new device types. Code using these device types 
SHOULD NEVER BE RELEASED. 



♦define clsMILTestlDevice 
♦define clsMILTest2Device 
♦define clsMILTest3Device 



MakeWKN (307, 1, wknGlobal) 
MakeWKN (315, 1, wknGlobal) 
MakeWKN (317, 1, wknGlobal) 
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Predefined conflict group uids. 

#define theMILConflictGroupl MakeWKN (418, 1, wknGlobal) 

#define theMILConflictGroup2 MakeWKN(419, 1, wknGlobal) 

#define theMILConflictGroup3 MakeWKN(420, 1, wknGlobal) 

♦define theMILConflictGroup4 MakeWKN(421, 1, wknGlobal) 

#define theMILConflictGroup5 MakeWKN(422, 1, wknGlobal) 

♦define theMILConflictGroup6 MakeWKN(423, 1, wknGlobal) 

♦define theMILConflictGroup7 MakeWKN (424, 1, wknGlobal) 

♦define theMILConflictGroup8 MakeWKN(425, 1, wknGlobal) 

♦define theMILConflictGroup9 MakeWKN(426, 1, wknGlobal) 

♦define theMILConflictGrouplO MakeWKN(427, 1, wknGlobal) 



The Connections Notebook 



♦define 


clsConnectionsUI 


♦define 


clsCNBSheet 


♦define 


clsConnections 


♦define 


clsPrinterView 


♦define 


clsPrinterViewCV 


♦define 


clsColumnView 


♦define 


theConnections 


♦define 


theVolumeServices 


♦define 


thePrinterServices 


♦define 


theConnectionsMenu 


♦define 


clsNetView 


♦define 


clsNetVolumeView 


♦define 


clsNetPrinterView 


♦define 


clsTOPSUI 


♦define 


clsConnectionsUIAppWin 



MakeWKN 


365, 


1, 


MakeWKN 


366, 


1, 


MakeWKN 


367, 


1, 


MakeWKN 


368, 


1, 


MakeWKN 


495, 


1, 


MakeWKN 


369, 


1, 


MakeWKN 


370, 


1, 


MakeWKN 


371, 


1, 


MakeWKN 


372, 


1, 


MakeWKN 


441, 


1, 


MakeWKN 


.373, 


1, 


MakeWKN 


374, 


1, 


MakeWKN 


375, 


1, 


MakeWKN 


376, 


1, 


MakeWKN 


377, 


1, 



wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 

wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 
wknGlobal 



Tr The Databases World 



♦define theDatabases 
♦define clsDbService 
♦define clsDBConnections 
♦define clsDatabasesView 
♦define clsDatabasesViewCV 
♦define clsTechGnosis 



MakeWKN (405, 

MakeWKN (406, 

MakeWKN (407, 

MakeWKN ( 408, 

MakeWKN (496, 

MakeWKN (437, 



1, wknGlobal ) 

1, wknGlobal ) 

1, wknGlobal ) 

1, wknGlobal ) 

1, wknGlobal ) 

1, wknGlobal ) 



^ The Hard Disk Installer 



♦define clsHardinst 
♦define theHardinst 



MakeWKN ( 225, 1, wknGlobal ) 
MakeWKN ( 436, 1, wknGlobal ) 



V The Symbolic Debugger 



♦define theDebugger 
♦define clsDebugger 



MakeWKN ( 358, 1, wknGlobal ) 
MakeWKN ( 358, 1, wknGlobal ) 



The ASP/AFP & AppleTalk Related Defines 



♦define clsASP MakeWKN (444, 1, wknGlobal) 

♦define clsASPClient MakeWKN (445, 1, wknGlobal) 

♦define clsASPServer MakeWKN (446, 1, wknGlobal) 
♦define clsASPServerSessionHandler MakeWKN (447, 1, wknGlobal) 

♦define clsVolAFP MakeWKN (448, 1, wknGlobal) 

♦define clsAFP MakeWKN (449, 1, wknGlobal) 

♦define clsAfpMounter MakeWKN (450, 1, wknGlobal) 

♦define theAfpMounter MakeWKN (451, 1, wknGlobal) 
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tdefine theSessionHandlers 
tdefine clsASPClientService 
tdefine clsASPServerService 

tdefine theAfpService 
tdefine theAfpVolumes 
tdefine clsAFPUI 

tdefine clsPcTest 
tdefine thePcTest 
tdefine thePublicFileTypes 



MakeWKN (452,1, wknGlobal ) 
MakeWKN(453, 1, wknGlobal) 
MakeWKN (454 , 1 , wknGlobal) 

MakeWKN (455, 1, wknGlobal) 
MakeWKN (456,1, wknGlobal ) 
MakeWKN (493, 1, wknGlobal) 

MakeWKN (4 97, 1, wknGlobal ) 
MakeWKN (498, 1, wknGlobal ) 
MakeWKN (499, 1, wknGlobal ) 
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APP.H 



This file contains the API definition for clsApp. The functions described in this file are contained in 
APP.LIB. 

clsApp inherits from clsObject. 

Provides the standard behavior for a PenPoint application. 



Introduction 



PenPoint applications rely on clsApp to create and display their main window, save state, terminate the 
application instance, and so on. Every application developer needs to create a descendant of clsApp and 
have the descendant handle a few important messages. See clsTemplateApp in 
\penpoint\sdk\sample\templtap for an example of those messages an application typically must handle. 

When the user turns to a document in the notebook, the PenPoint Application Framework creates an 
application instance to manage that document. Throughout this header file and the rest of our 
documentation, we use the term "document" to refer to an instance of an application class. 

#ifndef APP_INCLUDED 
#define APP_INCLUDED 

#ifndef FS_INCLUDED 
♦include <fs.h> 
#endif 



Common #defines and typedefs 

typedef OBJECT APP, *P_APP; 

tdefine AppDebug(v, e) DbgFlagCR', v, e) 



Well-known Filenames 



The Application Framework looks for information and stores document data in a series of well-known 
filenames. One of these is: 

♦ appResFileName, the application's resource file for its icons, quick help, user interface strings, and 
so on. 

Each document in the Notebook has its own directory, containing a collection of files for the 
document's data and subdirectories for any embedded documents. These are: 

♦ appDocStateFileName, the resource file for any objects that the document saves. In general, this is 
called the document's resource file 

♦ appDocResFileName, a resource file for preferences, including print metrics (once they are changed 
from the defaults) and comments that the user wrote in the "Comments" option sheet 

♦ appDocLinkFileName, the document's saved Reference Buttons and descriptors for what they are 
linked to 
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♦ appActiveDocLinkFileName, a working document of newly created (but not yet saved) Reference 
Buttons 

♦ appCorkboardDirName, the name of the subdirectory for documents embedded on the document's 
corkboard 

♦ subdirectories for any other embedded documents. 

#define appResFileName "APP.RES" 

♦define appDocStateFileName "DOCSTATE.RES" 

♦define appDocResFileName "DOC. RES" 

♦define appDocLinkFileName "DOC.LNK" 

♦define appActiveDocLinkFileName "ACTDOC.LNK" 

♦define appCorkboardDirName "CORKBD" 

Ifr Status Codes 



These are the status codes returned by clsApp. 



♦define 


stsAppRefused 


MakeStatus 


clsApp, 


1) 


♦define 


s t s AppMoveRCAppToCApp 


MakeStatus 


clsApp, 


2) 


♦define 


s t s AppMoveCAppTo Inval id 


MakeStatus 


clsApp, 


3) 


♦define 


s t sAppCopyRCAppToCApp 


MakeStatus 


clsApp, 


13) 


♦define 


st sAppCopyCAppTo Inval id 


MakeStatus 


clsApp, 


14) 


♦define 


stsAppNotMovable 


MakeStatus 


clsApp, 


4) 


♦define 


st sAppNot Copy able 


MakeStatus 


clsApp, 


5) 


♦define 


stsAppNotDeletable 


MakeStatus 


clsApp, 


6) 


♦define 


stsAppDuplicateName 


MakeStatus 


clsApp, 


7) 


♦define 


stsAppBadName 


MakeStatus 


clsApp, 


17) 


♦define 


s t sAppNot Found 


MakeStatus 


clsApp, 


8) 


♦define 


stsAppOpened 


MakeStatus 


clsApp, 


9) 


♦define 


stsAppNoSelection 


MakeStatus 


clsApp, 


10) 


♦define 


stsAppSelRequestNotSupported 


MakeStatus 


clsApp, 


11) 


♦define 


stsAppOutOfMemory 


MakeStatus 


ClsApp, 


15) 


♦define 


stsAppCrashed 


MakeStatus 


ClsApp, 


16) 


♦define 


stsAppOpenFailedSupressError 


MakeStatus 


ClsApp, 


18) 


♦define 


stsAppErrorStartingDoc 


MakeStatus 


ClsApp, 


19) 


♦define 


stsAppErrorEmbedPrintApply 


MakeStatus 


ClsApp, 


20) 


♦define 


stsAppErrorLeftPrintMargin 


MakeStatus 


clsApp, 


21) 


♦define 


stsAppErrorRightPrintMargin 


MakeStatus 


ClsApp, 


22) 


♦define 


stsAppErrorTopPrintMargin 


MakeStatus 


ClsApp, 


23) 


♦define 


stsAppErrorBottomPrintMargin 


MakeStatus 


ClsApp, 


24) 


♦define 


stsAppErrorHeaderPrintMargin 


MakeStatus 


clsApp, 


25) 


♦define 


stsAppErrorFooterPrintMargin 


MakeStatus 


ClsApp, 


26) 



Document States 



A document can be in one of three states. When the user opens a document, its state becomes 
appOpened. Once the user closes it, the document's state can be either appTerminated or appActivated. 

There are conditions when, after the user closes a document, the document's objects needs to stay 
around (and not be freed). Such conditions include when the document's access speed is set to 
accelerated (a.k.a., "hot mode") and when the document owns the selection. If a document is closed but 
needs to stay active, its state is set to appActivated. If there is no reason to keep a document around after 
it has been closed, its state becomes appTerminated (and the document is freed soon thereafter). 

You can specify additional conditions for keeping a closed document active by handling 
msgAppTerminateOK. See the description of this message for further details. 



♦define appTerminated 
♦define appActivated 1 
♦define appOpened 2 



// closed doc, on its way to being freed 
// closed doc, with a reason to stay active 
// opened doc 
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f^ App toggle | 

These are toggles used as parameters to various messages. 

♦define appOff 
tdefine appOn 1 
♦define appToggle 2 

Pjr Printing Flags 

The Application Framework uses these flags when opening a document to print it and its embedded 
documents. The typical application developer does not need to use these flags. However, if you open 
your own embedded documents, you should never pass on appPrintingTopLevel to them (even if you 
were opened with appPrintingTopLevel set). 

tdefine appPrinting ((U16)flag0) 
tdefine appPrintingTopLevel ((U16)flagl) 

ryr App Flags 

This structure defines the application flags. They include the state of the document (see Document 
States above) and other common booleans. This structure is used in APP_METRICS and by 
APP_DIR_FLAGS (defined in appdir.h). 



typedef struct APP_FLAGS { 
U16 state 



U16 


hotMode 


1; 


U16 


floating 


1; 


U16 


printing 


1; 


U16 


topLevel 


1; 


U16 


reservedl 


10; 


U16 


reserved2 


16; 



2; // Document state. 

// True = app is in hot mode. 

// True = app is floating. 

// True = app is printing. 

// True = app is printing as top level. 

// Reserved. 

// Reserved. 



} APP FLAGS, *P APP FLAGS; 



App Metrics 

This structure defines the public instance data for clsApp. You get a copy of this structure when you 
send msgAppGetMetrics to an application object. The fields of APP_METRICS are as follows: 

uuid: The documents uuid. It is stamped as an attribute on the document directory (see appdir.h). You 
can pass a document's uuid to clsDirHandle or clsAppDir in msgNew to create a handle to the 
document directory. 

dir: An instance of clsAppDir. It is the handle to the filesystem directory for a document. 

parent: An instance of clsApp. A document's parent is the document that activated it (see appmgr.h - 
msgAppMgrActivate). If the user opens a document from the Notebook, the Notebook is the parent. If 
the opened document is embedded within another document, its parent is the embeddor. 

children: An instance of clsObject. This represents a list of the documents that this document activated. 
There is often a one-to-one correspondence between a document's children and its embedded 
documents. 

mainWin: The document's main window. If this field is objNull when a document receives 
msgAppInit, the document self sends msgAppProvideMainWin to create one. 

floatingWins: An instance of clsList. It is the list of subordinate windows that are floating above a 
document (e.g., option sheets). See msgAppAddFloatingWin and msgAppRemoveFloatingWin for 
more info. 



UUID 


uuid; 


OBJECT 


dir; 


OBJECT 


parent ; 


OBJECT 


children; 


OBJECT 


mainWin; 


OBJECT 


floatingWins; 


OBJECT 


childAppParentWin; 


OBJECT 


resList; 


OBJECT 


resFile; 


U32 


reserved [2] ; 


APP_FLAGS 


flags ; 
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childAppParentWin: The preferred parent window for embedded documents. 

resList: An instance of clsResList. It is list of clsResFile objects. The default list consists of (1) a 
document resource file, (2) an application resource file, (3) a preference resource file, and (4) the system 
resource file. See resfile.h for more details. 

resFile: The document's resource file (the same one as in the resList). 

flags: Various flags for the document. See the discussion of APP_FLAGS given above. 

typedef struct APP_METRICS { 

// App uuid. 

// App directory. 

// Parent app. 

// Child apps observe this object. 

// App main window. 

// List of floating windows. 

// Root of child app window tree. 

// Resource file list. , 

// Document resource file. 

// Reserved. 

// Flags. 
} APP_METRICS, *P_APP_METRICS; 

Enabling and Disabling SAMs 

In its handler for msgAppCreateMenuBar, clsApp creates several menus and menu items that are part of 
PenPoint's standard user interface. These menus and items are known collectively as PenPoint's Standard 
Application Menus," or "SAMs" for short. The SAMs are identified by tags in apptag.h and are 
described in the PenPoint User Interface Design Reference. 

In many cases, descendants of clsApp should be involved in deciding when the SAM menu items should 
be enabled or disabled. Sometimes a descendant should completely remove an item from the SAM. 

To enable and disable the SAM items, clsApp handles msgControlProvideEnable (see control.h for a 
description this message). Specifically, clsApp: 

♦ Always enables: 

tagAppMenuPrint Setup 
t agAppMenuAbout 
tagAppMenuCheckpoint 
t agAppMenuRe ve rt 
tagAppMenuSearch 
tagAppMenuSpell 

♦ Enables this if theUndoManager has transactions to undo (see undo.h): 

tagAppMenuUndo 

♦ Asks the appropriate mananger to enable or disable: 

tagAppMenuPrint 
tagAppMenuSend 

♦ Always disables: 

tagAppMenuSelectAll 
any unrecognized tag 

Here are some examples of how descendants might want to modify the SAMs or respond to 
msgControlProvideEnable: 

♦ Most applications should support all of the features in the SAMs. (That's why they're part of 
PenPoint's standard UI.) But for a variety of reasons, some applications won't support some 
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standard PenPoint features. These applications should remove the menu item from the SAMs in q 

their handler for msgAppCreateMenuBar. (See msgAppCreateMenuBar below.) Menu items that 2 

might not be supported include: 



tagAppMenuPrint Setup 

tagAppMenuSearch 

tagAppMenuSpell 

tagAppMenuUndo 

tagAppMenuPrint 

tagAppMenuSend 

♦ Applications should handle msgControlProvideEnable and return false if there's no data in the 
application, true otherwise, for: 

tagAppMenuSelectAll 

Selection owners should respond to msgControlProvideEnable for tagAppMenuMove, 
tagAppMenuCopy and tagAppMenuDelete. Here are some notes on the proper response. 

♦ If there is no data selected, then all three items should be disabled. 

♦ If the application data is read-only, Move and Delete should be disabled. 

♦ In most other cases, the item should be enabled. 



^Messages 



msgNew 

Creates and initializes a new document. 

Takes P_APP_NEW, returns STATUS. Category: class message. 

Arguments typedef struct APP_NEW_ONLY { 

FS_LOCATOR locator; // Document's location in the filesystem. 

OBJECT winDev; // Window device. 

BOOLEAN appMonitor; // True if app monitor instance. 

U16 reservedl; // Reserved. 

U32 reserved2[4] ; // Reserved. 

} APP_NEW_ONLY, *P_APP_NEW_ONLY; 
#define appNewFields \ 

objectNewFields \ 

APP_NEW_ONLY app; 

typedef struct APP_NEW { 

appNewFields 
} APP_NEW, *P_APP_NEW; 

Comments clsApp initializes the new document's instance data to default values. 

You should never send msgNew directly to clsApp or its descendants. Sending msgNew is not sufficient 
to create a viable document. The document must have its own process and directory, which msgNew 
does not create. To create a viable document, send msgAppMgrCreate (or msgAppMgrCopy) followed 
by msgAppMgrActivate to the app's application manager. (Remember that the application manager's 
uid is the well-known uid for the application class.) 

Descendants: You should never handle msgNew directly. Instead, handle msglnit by initializing your 
instance data. The ancestor must be called before your msglnit handler. 
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msgNewDefaults 

Initializes an APP_NEW structure to default values. 

Takes P_APP_NEW, returns STATUS. Category: class message. 

Messoge typedef struct APP_NEW { 

Arguments appNewFields 

} APP_NEW, *P_APP_NEW; 

Comments Zeroes out pArgs->app. 

Descendants: You should handle msgNewDefaults by initializing your _NEW structure to default 
values. The ancestor must be called before your handler. 

msgFree 

Destroys a document. 

Takes nothing, returns STATUS. 

Comments The document frees its instance data, its children, its main window, and any option sheets it has created. 

Its final step is to kill its process, which means that flow of control never returns from this message 
handler. 

Descendants: You should handle msgFree by destroying all objects and resources you have created. The 
ancestor must be called after your handler. 



msgFreeOK 

Checks to see if a document and its children are willing to be freed. 

Takes nothing, returns STATUS. 

Comments This message is self sent as a result of msgDestroy being sent to the document. 

A document can be freed if it can be terminated (see above description of Document States). To 
determine if it can be terminated, the document self sends msgAppTerminateOK; if this message 
returns stsOK, the document then sends msgFreeOK to each active child document (those on the 
metrics.children list). If all of the children return stsOK, then the document can be terminated. 

Descendants: You normally do not handle this message. Instead, handle msgAppTerminateOK. 

Return Yalye stsOK If the document can be terminated. 

stsAppRefused If the document should not be terminated. 

msgAppActivate 

Activates a document and its children. 

Takes nothing, returns STATUS. 

tdefine msgAppActivate MakeMsg(clsApp, 1) 

Comments This message prepares an application to receive such requests as becoming available to the user 

(msgAppOpen) and searching for some data (msgAppSearch). 

Descendants: You normally do not handle this message. 
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msgAppInit 

Creates a document s default data file and main window. 

Takes DIR_HANDLE, returns STATUS. 

#define msgAppInit MakeMsg(clsApp, 2) 

Comments This message is sent the first time a document is activated. It performs one-time initializations. 

If the main window is objNull, the document creates the main window by self sending 
msgAppProvideMainWin. If childAppParentWin is objNull, the document sets it to be the main 
window. The document also sets the main window title by self sending msgAppGetName, followed by 
msgAppSetName. 

Descendants: You should handle this message by performing one-time initializations. This typically 
means creating any stateful objects that will be filed. The ancestor should be called before your handler. 



« 



msgAppRestore 

Restores a document from its saved instance data. 

Takes nothing, returns STATUS. 

#define msgAppRestore MakeMsg(clsApp, 3) 

Comments The document opens its resource file (appDocStateFileName), reads its instance data, and closes the 

file. When it receives msgRestore, the document reads its main window from the file. 

Descendants: You normally do not handle this message. Instead, you should handle msgRestore (which 
is sent as a result of this message). 

msgAppRestoreFrom 

Restores a document from a specified directory. 

Takes DIR_HANDLE, returns STATUS. 

♦define msgAppRestoreFrom MakeMsg(clsApp, 4) 

Comments This message is just like msgAppRestore, except the document opens the resource file 

(appDocStateFileName) located in DIR_HANDLE. 

Descendants: You normally do not handle this message. Instead, you should handle msgRestore (which 
is sent as a result of this message). 



msgAppSave 

Saves a document to its working directory. 

Takes nothing, returns STATUS. 

♦define msgAppSave MakeMsg(clsApp, 5) 

Comments The document self sends msgAppSaveChildren to save its children. Next, the document opens its 

resource file (appDocStateFileName), writes its instance data, and closes the file. The document also 
saves its link file. When it receives msgSave, the document writes its main window to the file. 

Descendants: You normally do not handle this message. Instead, you should handle msgSave to save 
your instance data. 
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msgAppSaveTo 

Saves a document to a specified directory. 
Takes DIR_HANDLE, returns STATUS. 

♦define msgAppSaveTo MakeMsg(clsApp, 6) 

This message is just like msgAppSave, except the document opens the resource file 
(appDocStateFileName) located in DIR_HANDLE. 

Descendants: You normally do not handle this message. Instead, you should handle msgSave to save 
your instance data. 



msgAppSaveChildren 

Saves a document's children. 

Takes nothing, returns STATUS. 

tdefine msgAppSaveChildren MakeMsg(clsApp, 7) 

The document self sends msgAppSaveChild to save each child document. 

Descendants: You normally do not handle this message. 



msgAppSaveChild 

Saves the specified child document. 

Takes APP, returns STATUS. 

fdefine msgAppSaveChild MakeMsg(clsApp, 97) 

The document sends msgAppSave to APP. 

Descendants: You normally do not handle this message. 

msgAppOpen 

Opens a document's main window. 

Takes P_APP_OPEN, returns STATUS. 

tdefine msgAppOpen MakeMsg(clsApp, 8) 

typedef struct APP_OPEN { 

OBJECT parent Win; // Document's parent window. 

OBJECT childAppParentWin; // out: Parent window for child apps. 

U16 printing; // in: See printing flags. 

} APP__OPEN, *P_APP_OPEN; 

If the document's main window has not been sized, the document sets it to the default size. It also 
updates the 'parentWin' and 'childAppParentWin' fields in the application metrics. The document then 
sets its state to appOpened and self sends msgAppOpenChildren to open its child documents. 

This message is sent to the document when it is to be made available to the user for direct interaction. 

Descendants: You should handle this message by creating any non-stateful objects that are necessary to 
display the document's UI. You should also fill in 'childAppParentWin' - normally with the document's 
client window. 
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You typically create the menu bar in response to this message. Self send msgAppCreateMenuBar to g 

create the menu bar, and then send msgFrameSetMetrics to your main window to insert the menu bar 2 

in the window. 



If you can't open the document, you should return stsFailed. However, if you have already displayed an 
error message to the user, then return stsAppOpenFailedSupressError. 

The ancestor should be called after your handler. 

msgAppClose 

Closes a document's main window. 

Takes nothing, returns STATUS. 

tdefine msgAppClose MakeMsg(clsApp, 9) 

Comments The document extracts its main window from the window tree. It then sets the 'parent Win' field in the 

application metrics to objNull and sets its state to appActivated. To close its children, it self sends 
msgAppCloseChildren. 

Descendants: You should handle this message by destroying any objects that you created in 
msgAppOpen. If you created the menu bar in your msgAppOpen handler, then you should send 
msgFrameDestroyMenuBar to your main window. The ancestor should be called before your handler. 

This message is not an indication to terminate the document; it may be followed by other requests for 
services such as searching or re-opening. 

msgAppSetMainWin 

Specifies a document's main window. 

Takes WIN, returns STATUS. 

tdefine msgAppSetMainWin MakeMsg(clsApp, 10) 

Comments The document updates its metrics.mainWin field to point to pArgs. It does not destroy the existing 

mainWin. 

Descendants: You normally do not handle this message. 



msgAppSetChildAppParentWin 

Specifies the window that is used as the parent window for child documents. 
Takes WIN, returns STATUS. 

tdefine msgAppSetChildAppParentWin MakeMsg(clsApp, 11) 

Descendants: You normally do not handle this message. 



msgAppGetMetrics 

Passes back a copy of the application metrics. 

Takes P_APP_METRICS, returns STATUS. 

tdefine msgAppGetMetrics MakeMsg(clsApp, 12) 

message typedef struct APP_METRICS { 

Arguments UUID uuid; // App uuid. 

OBJECT dir; // App directory. 

OBJECT parent; // Parent app. 
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OBJECT 


children; 


OBJECT 


mainWin; 


OBJECT 


floatingWins; 


OBJECT 


childAppParentWin; 


OBJECT 


resList; 


OBJECT 


resFile; 


U32 


reserved [2] ; 



APP_FLAGS flags; 
} APP METRICS, *P APP METRICS; 



// Child apps observe this object. 

// App main window. 

// List of floating windows. 

// Root of child app window tree. 

// Resource file list. 

// Document resource file. 

// Reserved. 

// Flags. 



Comments 



Descendants: You normally do not handle this message. 



Comments 



msgAppDispatch 

Starts message dispatching. 

Takes nothing, returns STATUS. 

#define msgAppDispatch MakeMsg(clsApp, 13) 

Descendants: You normally do not handle this message. 



msgAppRename 

Renames a document. 

Takes P_STRING, returns STATUS. 

Idefine msgAppRename MakeMsg(clsApp, 14) 

Comments After msgAppRename is sent to the document, the Application Framework sends msgAppSetName to 

change the document's window title. 

Descendants: You normally do not handle this message. Instead, you might want to handle 
msgAppSetName. 

msgAppSetName 

Specifies a document's displayed name (in its main window title). 

Takes P_STRING, returns STATUS. 

♦define msgAppSetName MakeMsg(clsApp, 15) 

Comments This message does not actually rename the document; it only sets the title of the document's main 

window. This message is sent to a document after it receives msgAppRename, which does rename the 
document. 

Descendants: You can handle this message by changing or adding to the string passed in. The ancestor 
will take the new string and display it in the document's title. The ancestor must be called after your 
handler. 



msgAppGetName 

Passes back a document's name. 

Takes P.STRING, returns STATUS. 

tdefine msgAppGetName MakeMsg(clsApp, 16) 

Comments The document passes back its name (not its main windows title). Note that P_STRING must be 

nameBufLength long. 

Descendants: You normally do not handle this message. 
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msgAppDelete § 

in 

Deletes a document from the system. S 

Takes nothing, returns STATUS. o. 

#define msgAppDelete MakeMsg(clsApp, 17) 

Comments The document deletes its appWin from its embeddor and sends msgAppMgrDelete to the document's 

class. 

Descendants: You normally do not handle this message. 

Return Value stsAppRefiised If metrics. flags. deletable is false. 

msgAppActivateChildren 

Activates a document's embedded documents. 

Takes nothing, returns STATUS. 

tdefine msgAppActivateChildren MakeMsg(clsApp, 18) 

Comments The document first activates the embedded documents that are stored in subdirectories of metrics.dir by 

self sending msgAppActivateChild for each child. It then self sends 

msgAppActivateCorkMarginChildren to activate the embedded documents that appear in the cork 
margin. 

Descendants: You normally do not handle this message. 



msgAppActivateCorkMarginChildren 

Activates embedded documents that are in a document's cork margin. 
Takes nothing, returns STATUS. 

#define msgAppActivateCorkMarginChildren MakeMsg(clsApp, 96) 
Comments The document self sends msgAppActivateChild for each embedded document in the cork margin. 

Descendants: You normally do not handle this message. 

msgAppActivateChild 

Instantiates and activates an embedded document. 

Takes P_APP_ACTIVATE_CHILD, returns STATUS. 

tdefine msgAppActivateChild MakeMsg(clsApp ; 19) 

Arguments typedef struct APP_ACTIVATE_CHILD { 

P_STRING pPath; // Path of child relative to self. 

APP uid; // out: Child app uid. 

} APP_ACTIVATE_CHILD, *P_APP_ACTIVATE_CHILD; 

Comments This message sends msgAppMgrActivate to activate the specified embedded document. 

Descendants: You normally do not handle this message. 

Return Vcslue stsAppRefiised If the child appDir.attrs.flags.disabled is true (see appdir.h). 
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msgAppAddFloatingWin 

Adds a window to a document s list of floating windows. 
Takes WIN, returns STATUS. 

tdefine msgAppAddFloatingWin MakeMsg(clsApp, 20) 

Comments Descendants: You normally do not handle this message. 

msgAppRemoveFloatingWin 

Removes a window from a document's list of floating windows. 
Takes WIN, returns STATUS. 

#define msgAppRemoveFloatingWin MakeMsg(clsApp, 21) 

Comments Descendants: You normally do not handle this message. 

msgAppFindFloatingWin 

Finds the floating window on a document's list of floating windows that matches the specified tag. 

Takes P_APP_FIND_FLOATING_WIN, returns STATUS. 

tdefine msgAppFindFloatingWin MakeMsg(clsApp, 22) 

Arguments typedef Struct APP_FIND_FLOATING_WIN { 

TAG tag; // in: tag to find. 

OBJECT win; // out: matching window, or objNull if not found. 

} APP_FIND_FLOATING_WIN, *P_APP_FIND_FLOATING_WIN; 

Comments Descendants: You normally do not handle this message. 

Return v«fye stsOK If the floating window is found 

stsNoMatch If the floating window cannot be found 

msgAppGetRoot 

Passes back a document's root document (which is typically the Notebook). 
Takes P_APP, returns STATUS. 

tdefine msgAppGetRoot MakeMsg(clsApp, 23) 

Comments Descendants: You normally do not handle this message. 

msgAppSetParent 

Specifies a document's parent document. 
Takes APP, returns STATUS. 

tdefine msgAppSetParent MakeMsg(clsApp, 24) 

Comments Descendants: You normally do not handle this message. 
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Comments 



msgAppSetHotMode 



Turns hot mode on or off for a document. 

Takes BOOLEAN, returns STATUS. 

tdefine msgAppSetHotMode MakeMsg(clsApp, 25) 

Descendants: You normally do not handle this message. 



Comments 



msgAppSetReadOnly 

Specifies a docuement's read only flag. 

Takes BOOLEAN, returns STATUS. 

#define msgAppSetReadOnly MakeMsg (clsApp, 26) 

Descendants: You normally do not handle this message. 



Comments 



msgAppSetDeletable 

Specifies a document's deletable flag. 

Takes BOOLEAN, returns STATUS. 

#define msgAppSetDeletable MakeMsg (clsApp, 27) 

Descendants: You normally do not handle this message. 



msgAppSetMovable 

Specifies a document's movable flag. Not implemented. 

Takes BOOLEAN, returns STATUS. 

tdefine msgAppSetMovable MakeMsg (clsApp, 28) 

See Also msgAppDirSetFlags 

msgAppSetCopyable 

Specifies a document's copyable flag. Not implemented. 
Takes BOOLEAN, returns STATUS. 

#define msgAppSetCopyable MakeMsg (clsApp, 29) 

See AIs© msgAppDirSetFlags 

Terminates a document. 

Takes BOOLEAN, returns STATUS. 

tdefine msgAppTerminate MakeMsg (clsApp, 30) 

Comments If true is passed in, the document is given the chance to veto the termination. It does this by self sending 

msgFreeOK to see if it is okay to free the document. If it is okay, the document saves itself by self 
sending msgAppSave, and then frees itself by self sending msgDestroy. 

If false is passed in, the document is not given the chance to veto. The document terminates itself and all 
of its children unconditionally. 
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Descendants: You normally do not handle this message. This message is a request, not a command, to 
terminate. It may be sent ANY number of times while a document is active. If you need to free objects 
when a document is terminated, you should handle msgFree. Furthermore, if you want to add 
conditions under which a document should not be terminated, handle msgAppTerminateOK. 

msgAppOpenChildren 

Opens all of the documents on a document's metrics.children list. 

Takes BOOLEAN, returns STATUS. 

tdefine msgAppOpenChildren MakeMsg(clsApp, 31) 

Comments If false is passed in, the document opens its child documents on screen by self sending 

msgAppOpenChild for each child. 

If true is passed in, it opens its child documents for printing as embedded documents. 

Descendants: You normally do not handle this message. 

msgAppOpenChild 

Opens a specific child of a document. 

Takes APP_OPEN_CHILD, returns STATUS. 

tdefine msgAppOpenChild MakeMsg(clsApp, 32) 

Arguments typedef struct APP_OPEN_CHILD { 

OBJECT app; // Document to open. 

U16 printing; // See printing flags. 

} APP_OPEN_CHILD, *P_APP_OPEN_CHILD ; 

Comments Opens the specified child document by creating a window for it and then sending it msgAppOpen. 

Descendants: You normally do not handle this message. 

msgAppCloseChildren 

Closes a document's children. 
Takes nothing, returns STATUS. 

tdefine msgAppCloseChildren MakeMsg(clsApp, 89) 

Comments The document self sends msgAppCloseChild for each of its child documents. 

Descendants: You normally do not handle this message. 

msgAppCloseChild 

Closes a specific child of a document. 
Takes APP, returns STATUS. 

tdefine msgAppCloseChild MakeMsg(clsApp, 90) 

Comments The document closes the specified child document by sending it msgAppClose. 

Descendants: You normally do not handle this message. 
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msgAppGetEmbeddor 

Passes back a document's direct parent in the file system heirarchy. 

Takes P_APP, returns STATUS. 

♦define msgAppGetEmbeddor MakeMsg (clsApp, 33) 

Comments The document finds its direct parent in the filesystem and passes back a pointer to it in P_APP. If the 

parent is not active, P_APP is set to null. 

Descendants: You normally do not handle this message. 



Arguments 



Comments 



msgAppTerminateOK 

Checks if a document is willing to terminate. 

Takes nothing, returns STATUS. 

tdefine msgAppTerminateOK MakeMsg (clsApp, 34) 

Comments The document self sends this message as a result of msgAppTerminate(true). The document refuses if: 

(1) the document is opened, (2) the document is in hot mode, or (3) the document or any object in the 
document owns the selection. 

Descendants: You should handle this message if you have your own conditions under which to veto 
document termination. Typically you call the ancestor first. If the ancestor returns stsAppRefused, then 
you also return this value. However, if your ancestor returns stsOK, you check for your veto conditions 
and return either stsOK or stsAppRefused. 

Ketum Voloe stsOK If the document can be terminated. 

stsAppRefused If the document should not be terminated. 



msgAppGetEmbeddedWin 

Finds the specified clsEmbeddedWin object within a document. 

Takes P_APP_GET_EMBEDDED_WIN, returns STATUS. 

tdefine msgAppGetEmbeddedWin MakeMsg (clsApp, 35) 



typedef Struct APP_GET_EMBEDDED_WIN { 

UUID uuid; // in: embedded win's uuid. 

OBJECT win; // out: embedded win. Set to objNull if no match. 

} APP_GET_EMBEDDED_WIN, *P_APP_GET_EMBEDDED_WIN; 

The document recursively enumerates its children, searching for a clsEmbeddedWin object with a 
matching embeddedWinMetrics.uuid (see embedwin.h). 

Descendants: You should handle this message only if you are managing embedded windows that are not 
in the main window's window tree. Typically you call the ancestor first. If the ancestor passes back a 
non-null win, then you don't need to do anything. However, if the ancestor passes back objNull for the 
win, you should check for a clsEmbeddedWin with a matching uuid. 



msgAppGetAppWin 

Finds a clsAppWin object within a document. 
Takes P_APP_GET_APP_WIN, returns STATUS. 



♦define msgAppGetAppWin 



MakeMsg (clsApp, 36) 
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Arguments typedef struct APP_GET_APP_WIN { 

UUID uuid; // in: app win's uuid. 

OBJECT win; // out: app win. Set to objNull if no match. 

} APP_GET_APP_WIN, *P_APP_GET_APP_WIN; 

Comments The document recursively enumerates its children, searching for a clsAppWin object with a matching 

appWinMetrics.appUUID (see appwin.h). 

Descendants: You should handle this message only if you are managing embedded windows that are not 
in the main window's window tree. Typically you call the ancestor first. If the ancestor passes back a 
non-null win, then you don't need to do anything. However, if the ancestor passes back objNull for the 
win, you should check for a clsAppWin with a matching uuid. 

msgAppOwnsSelection 

Tests if any object in a document owns the selection. 

Takes P_APP_OWNS_SELECTION, returns STATUS. 

tdefine msgAppOwnsSelection MakeMsg(clsApp, 37) 

Arguments typedef struct APP_OWNS_SELECTION { 

BOOLEAN checkChildren; // in: check child documents, too? 

BOOLEAN ownSelection; // out: true if doc(s) own the selection. 

} APP_OWNS_SELECTION, *P_APP_OWNS_SELECTION; 

Comments The document sets ownSelection to true if the selection belongs to itself or one of its children (if 

checkChildren is true). 

Descendants: You normally do not handle this message. 

msgAppOpenTo 

Opens a document to a specific state. 
Takes U32, returns STATUS. 

#define msgAppOpenTo MakeMsg(clsApp, 38) 

// States to pass to msgAppOpenTo 

#define appOpenToNormal // Open a doc in place. 

tdefine appOpenToFloating 1 // Open a doc to floating. 

#define appOpenToNextState 2 // Goto next state. Not Implemented. 

Comments If appOpenToNormal is passed in, the document sends msgAppOpenChild to its parent to open itself. 

If appOpenToFloating is passed in, the document self sends msgAppFloat to open itself. 

Descendants: You normally do not handle this message. 

msgAppCloseTo 

Closes a document to a specific state. 
Takes U32, returns STATUS. 

tdefine msgAppCloseTo MakeMsg(clsApp, 39) 

// States to pass to msgAppCloseTo 

tdefine appCloseToNormal // Close to icon, 

tdefine appCloseToNextState 1 // Close to next state. 

Comments Short description: you probably don't need to worry about this message. 

Long description: When the user taps on an embedded document icon, the document opens. If the user 
then double taps on the embedded document s title bar, the embedded document floats above its parent 
(allowing the user to resize it, without changing the layout of the parent). When the user closes the 
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floating document, it "closes" to its next state (i.e., open, but not floating). Closing it again closes the 
embedded document down to its icon. 

When the user closes an embedded document, the Application Framework sends the document 
msgAppCloseTo, passing it appCloseToNextState. However, the Application Framework needs a 
mechanism to close an embedded document all the way down to its icon (e.g., when the user closes the 
parent document). In such cases, the Application Framework sends msgAppCloseTo to the document, 
passing appCloseToNormal. 

Descendants: You normally do not handle this message. 



2 



msgAppHide 

Hides an open document. 

Takes nothing, returns STATUS. 

tdefine msgAppHide MakeMsg(clsApp, 40) 

Comments This message is used to get a document and all its associated windows off the screen as quickly as 

possible. It is usually followed (via ObjectPost) by msgAppClose, which is a heavier-weight message. 

The document (1) sends msgWinExtract to all windows in metrics.floatingWins, (2) sends 
msgWinExtract to metrics. mainWin, and (3) recursively sends msgAppHide to all documents on 
metrics.children. 

Descendants: You should handle this message if you have visible windows that are not children of the 
main window or in the floating window list. The ancestor should be called after your handler. 

msgAppSetFloatingRect 

Specifies a document's floating size and position. 
Takes P_RECT32, returns STATUS. 

tdefine msgAppSetFloatingRect MakeMsg(clsApp, 41) 

Comments Descendants: You normally do not handle this message. 



Comments 



msgAppSetOpenRect 

Specifies a document's open size and position. 

Takes P_RECT32, returns STATUS. 

tdefine msgAppSetOpenRect MakeMsg(clsApp, 42) 

Descendants: You normally do not handle this message. 



Arguments 



msgAppGetOptionSheet 

Passes back the requested option sheet of a document. 

Takes P_APP_GET_OPTION_SHEET, returns STATUS. 

tdefine msgAppGetOptionSheet MakeMsg(clsApp, 91) 

typedef struct APP_GET_OPTION_SHEET { 

TAG sheetTag; // in: tag of option sheet. 

OBJECT sheet; // out: sheet uid. 

} APP GET OPTION SHEET, *P APP GET OPTION SHEET; 
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Comments If the requested option sheet has already been created, the document just passes back its uid. 

Otherwise, it creates the sheet by self sending msgOptionCreateSheet. If the requested sheetTag is 
not tagAppDocOptSheet, the document self sends msgOptionAddCards to let descendants add option 
cards to the newly created sheet. 

Descendants: You normally do not handle this message. If you want to add other cards to the 
document's option sheets, you can handle msgAppAddCards. 

msgAppGetDocOptionSheetClient 

Passes back the client for a document's option sheets. 
Takes P_OBJECT, returns STATUS. 

♦define msgAppGetDocOptionSheetClient MakeMsg(clsApp, 93) 
Comments The document passes back its main window's client window. 

Descendants: You normally do not handle this message. 

msgAppAddCards 

Adds cards to the specified option sheet of a document. 

Takes P_OPTION_TAG, returns STATUS. 

#define msgAppAddCards MakeMsg(clsApp, 100) 

Comments If the specified sheet is tagAppAboutOptSheet, the document adds the "About Document" and "About 

Application" option cards to the sheet. If the sheet is tagAppDocOptSheet, the document adds the 
"Controls," "Access" and "Comments" cards. If the sheet is tagAppPrintSetupOptSheet, the document 
adds the "Print Layout" card. 

Descendants: You tend not to handle this message. However, you can handle it if you want to add cards 
to any of the document's option sheets. 



msgAppShowOptionSheet 

Shows or hides a document's option sheet. 

Takes P_APP_SHOW_OPTION_SHEET, returns STATUS. 

#define msgAppShowOptionSheet MakeMsg(clsApp, 92) 

Arguments typedef struct APP_SHOW_OPTION_SHEET { 

TAG sheetTag; // In: Option sheet tag. 

TAG cardTag; // In: Option card tag to initially show, or 

// null to show the top card. 
BOOLEAN show; // In: true = show, false = hide. 

OBJECT sheet; // Out: option sheet. 

} APP_SHOW_OPTION_SHEET, *P_APP_SHOW_OPTION_SHEET; 

Cssmswents The Application Framework sends this message to show (or hide) any of a document's option sheets. It 

is sent when, for example, the user picks any of the option cards from the SAMs or draws the check 
gesture on a document's title, over a selection, or over an embedded document icon. 

If show is true, the document self sends msgAppGetOptionSheet to get the requested option sheet. To 
display the sheet, the document sends msgOptionGetCards and msgOptionShowCardAndSheet to the 
sheet. 

If show is false, the document self sends msgAppFindFloatingWin and msgAppRemoveFloatingWin to 
find and then hide the requested option sheet. 

Descendants: You normally do not handle this message. 
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Comments 



msgAppApplyEmbeddeeProps 

Applies Embedded Printing option card values to first level embeddees. 
Takes OBJECT, returns STATUS. 

tdefine msgAppApplyEmbeddeeProps MakeMsg (clsApp, 98) 
Descendants: You normally do not handle this message. 



Arguments 



msgAppGetBorderMetrics 

Passes back a document's border metrics. 

Takes P_APP_BORDER_METRICS, returns STATUS. 



#define msgAppGetBorderMetrics 
// Border styles 
tdefine appBorderNone 
#define appBorderSingle 1 
tdefine appBorderDouble 2 
tdefine appBorderDashed 3 

typedef struct APP_BORDER_METRICS { 



MakeMsg ( cl s App , 94) 



U16 
U16 
U16 
U16 
U16 
U16 
U16 



controls 

titleLine 

menuLine 

corkMargin 

scrollMargins 

borderStyle 

reserved 



// Out 
// Out 
// Out 
// Out 
// Out 
// Out 



true /false, 
true /false, 
true /false, 
true /false, 
true/false. 
Border style. 



Comments 



} APP_BORDER_METRICS, *P_APP_BORDER_METRICS; 

Descendants: You normally do not handle this message. 



msgAppSetControls 

Turns a document's controls on or off. 

Takes U32, returns STATUS. 

tdefine msgAppSetControls MakeMsg (clsApp, 47) 

Comments If appOffis passed in, the document turns its controls off. If appOn is passed in, the controls are turned 

on. If appToggle is passed in, the document will toggle the state of the controls. 

Descendants: You normally do not handle this message. 

msgAppSetPrintControls 

Turns a document's screen decorations off for printing. 

Takes BOOLEAN, returns STATUS. 

tdefine msgAppSetPrintControls MakeMsg (clsApp, 99) 

Comments The document turns its controls off so that it can be printed. It leaves user-set borders on only if the 

document is printing itself as an embedded document (pArgs = false). 

Descendants: You normally do not handle this message. 
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msgAppSetTitleLine 

Turns a document's title line on or off. 

Takes U32, returns STATUS. 

fdefine msgAppSetTitleLine MakeMsg(clsApp, 44) 

Comments If appOff is passed in, the document hides its title line. If appOn is passed in, the title line is displayed. 

If appToggle is passed in, the document toggles whether the title line is displayed. 

Descendants: You normally do not handle this message. 

msgAppSetMenuLine 

Turns a document's menu bar on or off. 

Takes U32, returns STATUS. 

fdefine msgAppSetMenuLine MakeMsg(clsApp, 45) 

Comments If appOff is passed in, the document hides its menu bar. If appOn is passed in, the menu bar is 

displayed. If appToggle is passed in, the document toggles whether the menu bar is displayed. 

Descendants: You normally do not handle this message. 

msgAppSetCorkMargin 

Turns a document's cork margin on or off. 

Takes U32, returns STATUS. 

#define msgAppSetCorkMargin MakeMsg(clsApp, 48) 

If appOff is passed in, the document hides its cork margin. If appOn is passed in, the cork margin is 
created (if it doesn't exist) and displayed. If appToggle is passed in, the document toggles whether the 
cork margin is displayed. 

Descendants: You normally do not handle this message. 



Comments 



msgAppSetScrollBars 

Turns a document's scroll bars on or off. 

Takes U32, returns STATUS. 

♦define msgAppSetScrollBars MakeMsg(clsApp, 46) 

If appOff is passed in, the document hides its scroll bars. If appOn is passed in, the scroll bars are 
displayed. If appToggle is passed in, the document toggles whether the scroll bars are displayed. 

Descendants: You normally do not handle this message. 

msgAppSetBorderStyie 

Specifies the border style. 

Takes U32, returns STATUS. 

♦define msgAppSetBorderStyie MakeMsg(clsApp, 95) 

The possible values for pArgs are listed above in msgAppGetBorderMetrics. 

Descendants: You normally do not handle this message. 
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msgAppRevert 

Reverts to the filed copy of a document. 

Takes BOOLEAN, returns STATUS. 

tdefine msgAppRevert MakeMsg(clsApp, 49) 

Comments The document reverts to its previously saved state. If true is passed in, the document displays a note, 

asking the user to confirm the action first. If false is passed in, the document just does the action. 

Descendants: If you do not support revert, you should handle this message by returning stsAppRefused. 
On the other hand, if you support revert but you manage your own data files or use memory mapped 
files, then it may be necessary to handle this message by appropriately undoing all data modifications 
since the last save. The ancestor should be called before your handler. 

msgAppIsPageLevel 

Asks a document if it shows up as a page in the Notebook (as opposed to being embedded). 

Takes nothing, returns STATUS. 

♦define msgAppIsPageLevel MakeMsg(clsApp, 50) 

Comments Descendants: You normally do not handle this message. 

Return Value stsOK If the document is page-level (i.e., its embeddor inherits from clsContainerApp or 

clsRootContainerApp) . 

stsNoMatch If the document is not page-level. 
msgAppProvideMainWin 

Asks a document to provide its main window. 

Takes P_OBJECT, returns STATUS. 

#define msgAppProvideMainWin MakeMsg(clsApp, 51) 

Comments This message is sent during msgAppInit. If pArgs points to objNull, the document creates a default 

frame of type clsFrame and passes the frame's uid back in pArgs. 

Descendants: You should handle this message if you want to replace the default clsFrame main window. 
In such cases, you tend not to call the ancestor. 

See Also msgAppCreateClientWin 

msgAppCreateLink 

Creates a link from a document to another document. 

Takes P_APP_LINK, returns STATUS. 

Idefine msgAppCreateLink MakeMsg(clsApp, 52) 

Arguments typedef struct APP_LINK { 

UUID appUUID; // UUID of the document that is linked to. 
U32 link; // Link handle. 

} APP_LINK, *P_APP_LINK; 

Comments The uuid of the document to link to is passed in. The document passes back a link handle, which is 

used by msgAppGetLink to retrieve the document. The document stores the uuid in its 
appDocLinkFileName file. 

Descendants: You normally do not handle this message. 
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msgAppDeleteLink 

Deletes the specified link handle. 

Takes P_APP_LINK, returns STATUS. 

fdefine msgAppDeleteLink MakeMsg(clsApp, 53) 

Message typedef struct APP_LINK { 

Argyments UUID appUUID; // UUID of the document that is linked to. 

U32 link; // Link handle. 

} APP_LINK, *P_APP_LINK; 

Comments Descendants: You normally do not handle this message. 



msgAppGetLink 

Passes back a document's UUID for the specified link handle. 

Takes P_APP_LINK, returns STATUS. 

♦define msgAppGetLink MakeMsg(clsApp, 54) 

Message typedef struct APP_LINK { 

Arguments UUID appUUID; // UUID of the document that is linked to. 

U32 link; // Link handle. 

} APP_LINK, *P_APP_LINK; 

Comments Descendants: You normally do not handle this message. 

Standard Application Menu Messages 



msgAppCreateMenuBar 

Creates the standard application menu bar. 

Takes P_OBJECT, returns STATUS. 

#define msgAppCreateMenuBar MakeMsg(clsApp, 55) 

Descendants: You should handle this message by creating the document's menu bar. If pArgs is non-null 
when the ancestor is called, clsApp will pre-pend the Document, Edit, and Option menus to the 
provided menu bar. So you should call the ancestor after you make the menu bar. After the ancestor 
returns, you can fix up the Document and Edit menus to remove any buttons that you don't support or 
to add any new buttons. 

See the earlier description "Enabling and Disabling SAMs" for more details. 

msgAppCreateClientWin 

Creates a document's client window. 

Takes P_OBJECT, returns STATUS. 

#define msgAppCreateClientWin MakeMsg(clsApp, 56) 

The document creates a default client window of class clsEmbeddedWin and passes back its uid. 

The Application Framework does not send this message by default. Instead, you should self send it at 
the appropriate time (typically during msgAppInit, since the client window is usually stateful). 

Descendants: You should handle this message by creating your application- specific client window. In 
such cases, you tend not to call your ancestor. 
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msgAppSend 

Sends a document. 

Takes OBJECT, returns STATUS. 

tdefine msgAppSend MakeMsg(clsApp, 57) 

Comments When the user taps on a button in the Send menu, the SAMs send this message to the document, 

passing in theSendManager. The document then self sends msgAppInvokeManager, passing on 
theSendManager. 

Descendants: You normally do not handle this message. 



2 



msgAppPrint 

Prints a document. 

Takes OBJECT, returns STATUS. 

tdefine msgAppPrint MakeMsg(clsApp, 58) 

Comments When the user issues the Print command (either by tapping on the Print button in the SAMs or by 

drawing the print gesture on the document s title line), the Application Framework sends this message to 
the document, passing it thePrintManager. The document then self sends msgAppInvokeManager, 
passing on thePrintManager. 

Descendants: You normally do not handle this message. 

msgAppPrintSetup 

Displays a document's print setup option sheet. 

Takes nothing, returns STATUS. 

tdefine msgAppPrintSetup MakeMsg(clsApp ; 59) 

Comments When the user taps on Print Setup, the SAMs send this message to the document. The document self 

sends msgAppOptionShowOptionSheet, passing it tagAppPrintSetupOptSheet. 

Descendants: You normally do not handle this message. 



See Also 



msgAppImport 

Obsolete message. Not implemented. 
Takes nothing, returns STATUS. 
tdefine msgAppImport 
msglmport 



MakeMsg(clsApp, 60) 



Comments 



msgAppExport 

Prepares to export a document as a file. 

Takes OBJECT, returns STATUS. 

tdefine msgAppExport MakeMsg(clsApp, 61) 

The document self sends msgAppInvokeManager, passing on pArgs. 

Descendants: You normally do not handle this message. 
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msgAppAbout 

Displays a document's "About" option sheet. 

Takes nothing, returns STATUS. 

tdefine msgAppAbout MakeMsg(clsApp, 62) 

Comments When the user taps on About, the SAMs send this message to the document. The document self sends 

msgAppOptionShowSheet, passing it tagAppAboutOptSheet. 

Descendants: You normally do not handle this message. Instead, you should handle 
msgOptionAddCards by adding more cards to the About option sheet. Likewise, you should handle 
msgOptionProvideCard by modifying or adding specific controls to the standard About cards. 

msgAppHelp 

Shows help for the application. Not implemented - Reserved. 

Takes nothing, returns STATUS. 

tdefine msgAppHelp MakeMsg(clsApp, 63) 

Comments Descendants: You should not handle this message. Instead, you can provide help via resource files (see 

the Tic-Tac-Toe sample application for an example). 

msgAppUndo 

Undoes the previous operation on a document. 

Takes nothing, returns STATUS. 

tdefine msgAppUndo MakeMsg(clsApp, 64) 

Comments The document sends msgUndoCurrent to theUndoManager. 

Descendants: You normally do not handle this message. Instead, see UNDO.H for information on how to 
undo your application's commands. 

msgAppMoveSel 

Prepares to move a document's selection. 

Takes nothing, returns STATUS. 

tdefine msgAppMoveSel MakeMsg(clsApp, 65) 

Comments When the user issues the Move command (either by tapping on Move in the SAMs or by press-holding 

on a selection in the document), the Application Framework sends this message to the document. The 
document finds its selected object (by sending msgSelOwner to theSelectionManager) and then sends it 
msgSelBeginMove. 

Descendants: You normally do not handle this message. 



msgAppCopySel 

Prepares to copy the document's selection. 

Takes nothing, returns STATUS. 

tdefine msgAppCopySel MakeMsg(clsApp, 66) 
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Comments When the user issues the Copy command (either by tapping on Copy in the SAMs or by 

tap-press-holding on a selection in the document), the Application Framework sends this message to the 
document. The document finds its selected object (by sending msgSelOwner to theSelectionManager) 
and then sends it msgSelBeginCopy. 

Descendants: You normally do not handle this message. 



Comments 



msgAppDeleteSel 

Deletes a document's selection. 

Takes nothing, returns STATUS. 

♦define msgAppDeleteSel MakeMsg(clsApp, 67) 

Comments When the user issues the Delete command (either by tapping on Delete in the SAMs or by drawing the 

delete gesture, the Application Framework sends this message to the document. The document gets its 
selected object (by sending msgSelOwner to theSelectionManager) and then sends it msgSelDelete. 

Descendants: You normally do not handle this message. 

msgAppSelOptions 

Prepares to display the options for a document's selection. Obsolete. 
Takes nothing, returns STATUS. 

♦define msgAppSelOptions MakeMsg(clsApp, 68) 

Comments Descendants: You should not handle this message. 



msgAppSelectAll 

Selects all of the objects in a document. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

♦define msgAppSelectAll MakeMsg(clsApp, 69) 

When the user taps on Select All in the Standard Application Menu, the document self sends this 
message. 

clsApp does not do anything in its message handler for this message. 

Descendants: You should handle this message and select everything in the document. You tend not to 
call the ancestor. 



2 



Comments 



msgAppSearch 

Searches a document for a string. 

Takes OBJECT, returns STATUS. 

♦define msgAppSearch MakeMsg(clsApp, 70) 

When the user issues the Find command (either by tapping on Find in SAMs or by drawing the find 
gesture on the document's title line), the Application Framework sends this message to the document, 
passing it theSeachManager. In response, the document self sends msgAppInvokeManager, passing on 
theSearchManager. 

Descendants: You normally do not handle this message. 
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msgAppSpell 

Prepares to check a document's spelling. 

Takes OBJECT, returns STATUS. 

#define msgAppSpell MakeMsg(clsApp, 71) 

Comments When the user issues the Spell command (either by tapping on Spell in SAMs or by drawing the spell 

gesture on the document's title line), the Application Framework sends this message to the document, 
passing it theSpellManager. In response, the document self sends msgAppInvokeManager, passing on 
theSpellManager. 

Descendants: You normally do not handle this message. 

msgAppInvokeManager 

Routes a message to a manager. 

Takes OBJECT, returns STATUS. 

tdefine msgAppInvokeManager MakeMsg(clsApp, 72) 

Comments To route a standard application menu message to the object that provides the behavior, the document 

self sends msgAppInvokeManager. The argument to the message is the well-known UID of the manager 
that performs the operation. When the document receives msgAppInvokeManager, it sends 
msgAppExecute to the manager object. 

Descendants: You normally do not handle this message. 

msgAppExecute 

Sent to the manager to execute the manager's behavior on a document. 

Takes P_APP_EXECUTE, returns STATUS. 

tdefine msgAppExecute MakeMsg(clsApp, 73) 

Arguments typedef struct APP_EXECUTE { 

OBJECT app; // Requesting document. 

OBJECT sel; // Selected object. 

U32 count; // Number of uuids. 

UUID uuidfl]; // UUIDs of documents to operate on. 
} APP_EXECUTE, *P_APP_EXECUTE; 

Comments The document sends msgAppExecute to a manager when it receives msgAppInvoke manager. The 

manager performs some operation on the document or documents specified in the pArgs, such as 
printing, searching, or spell checking. 

Descendants: You normally do not handle this message. 
msgAppExecuteGesture 

Invokes the default gesture behavior for a document's title line. 

Takes P_GW1N_GESTURE, returns STATUS. 

#define msgAppExecuteGesture MakeMsg(clsApp, 74) 

Comments Descendants: You normally do not handle this message. However, if you want to handle a title line 

gesture differently than the default, you should handle this message. You tend not to call the ancestor. 
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msgAppSetSaveOnTerminate § 

in 

Tells a document to save itself before terminating. ^ 

Takes BOOLEAN, returns STATUS. £ 

a. 

♦define msgAppSetSaveOnTerminate MakeMsg(clsApp, 75) 

If msgAppSetSaveOnTerminate has been sent before msgAppTerminate, the document will be sent 
msgAppSave even if it refuses to terminate. Normally, if a document vetos msgAppTerminate, it is not 
sent msgAppSave. 

Descendants: You normally do not handle this message. 



Notification messages 



msgAppTerminateConditionChanged 

Try to terminate a document; sent when a terminate condition changed. 

Takes nothing, returns STATUS. 

#define msgAppTerminateConditionChanged MakeMsg(clsApp, 76) 

Comments In response to this message, the document self sends msgAppTerminate(true). 

This message is self sent when a terminate condition has changed. For example, the document might 
have given up its selection and can now be terminated. 

Descendants: You normally do not handle this message. Instead, see msgAppTerminateOK. 

Sent to a document when something in it becomes selected or deselected. 

Takes BOOLEAN, returns STATUS. 

#define msgAppSelChanged MakeMsg(clsApp, 77) 

Comments pArgs is true when the document (or one of its embedded documents) gains the selection. pArgs is false 

when the selection leaves the document. 

The document self sends msgAppTerminateConditionChanged when it no longer has the selection. 

Descendants: You normally do not handle this message. 

msgAppOpened 

Sent to observers of a document when the document is opened. 
Takes APP_OPENED, returns STATUS. Category: observer notification, 
♦define msgAppOpened MsgNoError(MakeMsg(clsApp, 78)) 

Comments pArgs->child is the uid of the document that has been opened. 

msgAppClosed 

Sent to observers of a document when the document is closed. 
Takes APP_CLOSED, returns STATUS. Category: observer notification. 
#define msgAppClosed MsgNoError(MakeMsg(clsApp, 79)) 

Ccsmmersts pArgs->child is the uid of the document that has been closed. 
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msgAppChildChanged 

Sent to observers of a document when a child document is opened or closed. 

Takes P_APP_CHILD_CHANGED, returns STATUS. Category: observer notification. 

#define msgAppChildChanged MsgNoError (MakeMsg (clsApp, 80)) 

Arguments typedef struct APP_CHILD_CHANGED { 

OBJECT parent; // Parent of doc that changed. 

OBJECT child; // Doc that changed. 

UUID uuid; // UUID of doc that changed. 

MESSAGE change; // msgAppOpened or msgAppClosed. 

U32 reserved[4]; // Reserved. 

} APP_CHILD_CHANGED, *P_APP_CHILD_CHANGED, 
APP_0PENED, *P_APP_0PENED, 
APP_CL0SED, *P_APP_CL0SED; 

Comments This message is sent to observers of a document in response to msgAppOpened and msgAppClosed. 



Arguments 



msgAppFloated 

Sent to observers when a document is floated or un-floated. 

Takes P_APP_FLOATED, returns STATUS. Category: observer notification, 
♦define msgAppFloated MsgNoError (MakeMsg (clsApp, 81)) 

typedef struct APP_FL0ATED { 

OBJECT app; // Document that is floated or un-floated. 

BOOLEAN floatUp; // true=document is floated. 

} APP FLOATED, *P APP FLOATED; 



Arcjymersfs 



msgAppCreated 

Sent to observers of clsApp when a document is created. 

Takes P_APP_CREATED, returns STATUS. Category: observer notification. 



tdefine msgAppCreated 

typedef struct APP_CREATED { 

OBJECT rootContainer; 

UUID rootContainerUUID; 

UUID uuid; 

U32 reserved [4]; 
} APP CREATED, *P APP CREATED; 



MsgNoError (MakeMsg (clsApp, 82) ) 



// Root container uid. 
// Root container uuid. 
// Created doc's uuid. 
/■/ Reserved. 



Arguments 



msgAppDeleted 

Sent to observers of clsApp when a document is deleted. 

Takes P_APP_DELETED, returns STATUS. Category: observer notification. 



tdefine msgAppDeleted 

typedef struct APP_DELETED { 

OBJECT rootContainer; 

UUID rootContainerUUID; 

OBJECT app; 

UUID uuid; 

U32 reserved [4]; 
} APP DELETED, *P APP DELETED; 



MsgNoError (MakeMsg (clsApp, 83)) 

// Root container uid. 

// Root container uuid. 

// Deleted document. objNull if inactive. 

// Deleted document's uuid. 

// Reserved. 
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OBJECT 


rootContainer; 


UUID 


root Cont ainerUUID ; 


OBJECT 


app; 


UUID 


uuid; 


U32 


moveCopylnfo; 


U32 


reserved [4] ; 



♦define msgAppMoved MsgNoError (MakeMsg(clsApp, 84)) 

// Move/copy values for moveCopylnfo argument 

#define appMovedCopiedlnto // doc moved/copied to this root container 

tdefine appMovedCopiedOutOf 1 // doc moved/copied from this root container 

tdefine appMovedCopiedWithin 2 // doc moved/copied within this root container 

Arguments typedef Struct APP_MOVED_COPIED { 

// Root container uid. 

// Root container uuid. 

// Moved/copied doc. objNull if inactive. 

// Moved/ copied document's uuid. 

// Type of move /copy. 

// Reserved. 
} APP_MOVED_COPIED, *P_APP_MOVED_COPIED; 

Comments When a document is moved, the Application Framework notifies the observers of clsApp that a 

document has moved either a) within a root container, or b) out of one root container and into another. 
(It may help you to remember that root containers are typically notebooks.) 

To notify the observers, the Application Framework creates a list containing the document that is being 
moved and each of its embedded documents. If the document is being moved within the root container, 
then for each of the documents in the list, the Application Framework sends msgAppMoved to the 
observers of clsApp, specifying appMovedCopiedWithin. If the document is being moved from one 
container to another, the Application Framework sends msgAppMoved twice for each document, once 
specifying appMovedCopiedOutOf and once specifying msgMovedCopiedlnto. 

See Mm msgAppChanged 



msgAppCopied 

Sent to observers of clsApp when a document is copied. 

Takes P_APP_MOVED_COPIED, returns STATUS. Category: observer notification. 

tdefine msgAppCopied MsgNoError (MakeMsg( clsApp, 85)) 

message typedef struct APP_MOVED_COPIED { 

Arguments OBJECT rootContainer; // Root container uid. 

UUID rootContainerUUID; // Root container uuid. 

OBJECT app; // Moved/copied doc. objNull if inactive. 

UUID uuid; // Moved/copied document's uuid. 

U32 moveCopylnfo; // Type of move/copy. 

U32 reserved[4]; // Reserved. 

} APP_MOVED_COPIED, *P_APP_MOVED_COPIED; 

Comments When a document is copied, the Application Framework notifies the observers of clsApp that a 

document has been copied either a) within a root container, or b) from one root container into another. 
(It may help you to remember that root containers are typically notebooks.) 

To notify the observers, the Application Framework creates a list containing the document that is being 
copied and each of its embedded documents. If the document is being copied within the root container, 
then for each of the documents in the list, the Application Framework sends msgAppCopied to the 
observers of clsApp, specifying appMovedCopiedWithin. If the document is being copied from one 
container to another, the Application Framework sends msgAppCopied twice for each document, once 
specifying appMovedCopiedOutOf and once specifying msgMovedCopiedlnto. 

See Also msgAppChanged 



msgAppMoved § 

ui 

Sent to observers of clsApp when a document is moved. 

Takes P_APP_MOVED_COPIED, returns STATUS. Category: observer notification. 
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Comments 



msgAppChanged 

Sent to observers of clsApp when a document has changed. 

Takes P_APP_CHANGED, returns STATUS. Category: observer notification. 

♦define msgAppChanged MsgNoError(MakeMsg(clsApp, 86)) 

// State of a doc's bookmark (which is interpreted in the NUI as a tab) 
♦define appBookmarkOn 1 
♦define appBookmarkOff 2 



typedef struct APP_CHANGED { 
OBJECT rootContainer; 
UUID rootContainerUUID; 
UUID uuid; 
OBJECT uid; 
U16 globalSequence : 1; 



U32 reserved2[4]; 
APP CHANGED, *P APP CHANGED; 



U16 


name 


U16 


bookmark 


U16 


create 


U16 


deleted 


U16 


move 


U16 


copy 


U16 


reservedl 


U16 


moveCopylnfo; 



// In: Root container uid. 

// In: Root container uuid. 

: The uuid of the changed document. 

: objNull if changed doc was not active. 

; true if doc's container (i.e., 
// notebook) needs to be renumbered. 

// In: true if doc's name changed 

// In: new bookmark state, if changed 

// In: true if doc is new 

// In: true if doc was deleted 

: true if doc was moved 

: true if doc was copied 



// In: 
// In: 
// In: 



// In: 
// In: 



// In: if doc was moved or copied, this 
// is set to move/copy value described 
//in msgAppMoved. 



This message is sent to observers of clsApp when a document has changed in some way (e.g., the 
document has moved, has a new name, has been created, and so on). 

When a document is moved or copied, this message is sent to observers of clsApp. However, it is not 
sent for all of the document's embedded documents (thereby making it different from msgAppMoved 
and msgAppCopied). 

msgAppMoved 



Comments 



msgAppInstalled 

Sent to observers of clsApp when an application is installed. 

Takes CLASS, returns STATUS. Category: observer notification. 

♦define msgAppInstalled MsgNoError (MakeMsg (clsApp, 87)) 

pArgs is the class of the application just installed. 



Comments 



msgAppDelnstalled 

Sent to observers of clsApp when an application is deinstalled. 

Takes CLASS, returns STATUS. Category: observer notification. 

♦define msgAppDelnstalled MsgNoError (MakeMsg (clsApp, 88)) 

pArgs is the class of the application just deinstalled. 
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Public Functions 



AppMain 

Creates a document instance and starts dispatching messages to it. 

Returns nothing. 
Function Prototype STATUS EXPORTED AppMain (void) ; 

Comments All developers should call AppMain from their main routine whenever processCount is greater than 0. 

AppMonitorMain 

Creates an app monitor instance and handles installing the application. 
Returns nothing. 

Function Prototype STATUS EXPORTED AppMonitorMain (OBJECT, OBJECT) ; 

Comments All developers should call AppMonitorMain from their main routine when processCount is equal to 0. 

You specify the well-known uid of your application class and the well-known uid of your app monitor 
class. If you do not have an app monitor class, simply specify objNull for the second parameter. 
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APPDIR.H 



This file contains the API definition for clsAppDir. 
clsAppDir inherits from clsDirHandle. 
Provides management for document directories. 
"AppDir" stands for Application Directory Handle. 



Introduction 



Application directory nodes represent documents in the document hierarchy. Application directories are 
where documents store their resource files and any other files they use. Attributes on application 
directories specify useful information about each document. 

clsAppDir is used to manage the various file system attributes associated with a document in PenPoint. 
It includes definitions of these attributes and messages to manage them. clsAppDir also provides support 
for enumerating embedded documents via the filesystem. This is similar to the file system's FSReadDir 
facilities, but clsAppDir filters out all files and directories that are not documents. 

A document can find its application directory by self sending msgAppGetMetrics. The application 
directory's uid will be passed back in the dir field of the APP_METRICS structure. See app.h for more 
information. 

Application directories are created automatically for documents during Applnit time by the Application 
Framework. Application classes generally should never create or destroy application directories 
themselves. 

tifndef APPDIR_INCLUDED 
♦define APPDIR_INCLUDED 
tifndef APP_INCLUDED 
♦include <app.h> 
tendif 



Common #defines and typedefs 

typedef OBJECT APP_DIR, *P_APP_DIR; 

File System Attributes 

These attributes are stamped on every document directory. 



♦define appAttrClass 
tdefine appAttrSequence 
♦define appAttrNumChildren 
tdefine appAttrFlags 
tdefine appAttrBookmark 
tdefine appAttrAuthor 
tdefine appAttr Comments 
tdefine appAttrClassName 
tdefine appAttrGlobalSequence 



FSMakeFix32Attr (clsAppDir, 1) 
FSMakeFix32Attr (clsAppDir, 4) 
FSMakeFix32Attr (clsAppDir, 3) 
FSMakeFix64Attr (clsAppDir, 6) 
FSMakeStrAttr (clsAppDir, 9) 
FSMakeStrAttr (clsAppDir, 10) 
FSMakeStrAttr (clsAppDir, 11) 
FSMakeStrAttr (clsAppDir, 12) 
FSMakeFix32Attr (clsAppDir, 4) 
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Application Directory Flags 

This structure defines the application directory flags. They are stamped on a document directory with 
appAttrFlags. This structure is used in the flags field of APP_DIR_ATTRS. 



typedef struct APP_DIR FLAGS { 



U16 


application 


1; 


D16 


newlnstance 


1; 


U16 


disabled 


1; 


U16 


bookmark 


1; 


U16 


readonly 


1; 


U16 


deletable 


1; 


U16 


movable 


1; 


U16 


copyable 


1; 


U16 


reservedl 


8; 


U16 


reserved2 


16 


U16 


reserved3 


16 


U16 


reserved4 


16 


} APP_DIR_ 


FLAGS, *P APP DIR I 


n LAG 



// true = this is an application. 

// true = new app instance. 

// true = app is disabled, don't activate. 

// true = app has a tab 

// True = app is read only. 

// true = app can be deleted. 

// true = app can be moved. 

// true = app can be copied. 

// Reserved. 

// Reserved. 

// Reserved. 

// Reserved. 



Application Directory Attributes Structure 

This structure is used to specify and pass back the directory attributes in one chunk. 



appClass The document's application class (sub-class of clsApp). 

uuid The document's uuid. Can be used in msgNew to clsDirHandle or clsAppDir to open a 
handle on a document directory. 

sequence The 1 -based position of a document within its embeddor. If the document is in a 
notebook, this is the document's position within its section. 

numChildren The total number of embedded children. 



typedef struct APP_DIR_ATTRS { 

CLASS appClass; 

UUID uuid; 

U32 sequence; 

U32 numChildren; 

APP_DIR_FLAGS flags; 
} APP DIR ATTRS, *P APP DIR ATTRS; 



// Application class. 

// Application uuid. 

// Local sequence number. 

// Number of child apps (recursive) 

// Flags. 



Messages 



msgNew 

Creates a new AppDir. 

Takes P_FS_NEW, returns STATUS. Category: class message. 

See fs.h for the FS_NEW structure definition. 

clsAppDir has no method for msgNewDefaults. See fs.h for a description of clsDirHandle's handler for 
msgNewDefaults. 
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msgAppDirGetAttrs § 

ui 

Passes back a document's application directory attributes. 

Takes P_APP_DIR_GET_SET_ATTRS, returns STATUS. a. 

Q. 

tdefine msgAppDirGetAttrs MakeMsg (clsAppDir, 1) 

Arguments typedef Struct APP_DIR_GET_SET_ATTRS { 

P_STRING pPath; // in: Path relative to target directory. 

APP_DIR_ATTRS attrs; // in/out: Application directory attributes. 
} APP_DIR_GET_SET_ATTRS, *P_APP_DIR_GET_SET_ATTRS; 

Comments If you are interested in only one of the attributes, use the individual msgAppDirGet... messages 

described below. They're generally faster. 

msgAppDirSetAttrs 

Specifies a document's application directory attributes. 

Takes P_APP_DIR_GET_SET_ATTRS, returns STATUS. 

tdefine msgAppDirSetAttrs MakeMsg (clsAppDir, 2) 

Message typedef struct APP_DIR_GET_SET_ATTRS { 

Arguments P_STRING pPath; // in: Path relative to target directory. 

APP_DIR_ATTRS attrs; // in/out: Application directory attributes. 
} APP_DIR_GET_SET_ATTRS, *P_APP_DIR_GET_SET_ATTRS; 

Comments If you are interested in only one of the attributes, use the individual msgAppDirSet... messages 

described below. They're generally faster. 

msgAppDirGetFlags 

Passes back a document's application directory flags. 

Takes P_APP_DIR_GET_SET_FLAGS, returns STATUS. 

tdefine msgAppDirGetFlags MakeMsg (clsAppDir, 3) 

Arguments typedef Struct APP_DIR_GET_SET_FLAGS { 

P_STRING pPath; // in: Path relative to target directory. 

APP_DIR_FLAGS flags; // in/out: Application directory control flags. 
} APP_DIR_GET_SET_FLAGS, *P_APP_DIR_GET_SET_FLAGS; 

msgAppDirSetFlags 

Specifies a document's application directory flags. 

Takes P_APP_DIR_GET_SET_FLAGS, returns STATUS. 

tdefine msgAppDirSetFlags MakeMsg (clsAppDir, 4) 

Messoge typedef struct APP_DIR_GET_SET_FLAGS { 

Arguments P_STRING pPath; // in: Path relative to target directory. 

APP_DIR_FLAGS flags; // in/out: Application directory control flags, 
} APP DIR GET SET FLAGS, *P APP DIR GET SET FLAGS; 
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msgAppDirGetClass 

Passes back a document's application class. 

Takes P_APP_DIR_UPDATE_CLASS, returns STATUS. 

#define msgAppDirGetClass MakeMsg(clsAppDir, 5) 

typedef struct APP_DIR_UPDATE_CLASS { 

P_STRING pPath; // in: Path relative to target directory. 

CLASS appClass; // in/out: Application directory class. 
} APP DIR UPDATE CLASS, *P APP DIR UPDATE CLASS; 



msgAppDirSetClass 

Specifies a document's application class. 

Takes P_APP_DIR_UPDATE_CLASS, returns STATUS. 

♦define msgAppDirSetClass MakeMsg(clsAppDir, 6) 

typedef struct APP_DIR_UPDATE_CLASS { 

P_STRING pPath; // in: Path relative to target directory. 

CLASS appClass; // in/out: Application directory class. 

} APP DIR UPDATE CLASS, *P APP DIR UPDATE CLASS; 



msgAppDirGetUUID 

Passes back an application directory's uuid. 

Takes P_APP_DIR_UPDATE_UUID, returns STATUS. 

#define msgAppDirGetUUID MakeMsg(clsAppDir, 7) 

typedef struct APP_DIR_UPDATE_UUID { 

P_STRING pPath; // in: Path relative to target directory. 

UUID uuid; // in/out: Application directory uuid. 

} APP DIR UPDATE UUID, *P APP DIR UPDATE UUID; 



msgAppDirSetUUID 

Specifies an application directory's uuid. 

Takes P_APP_DIR_UPDATE_UUID, returns STATUS. 

♦define msgAppDirSetUUID MakeMsg(clsAppDir, 8) 

typedef struct APP_DIR_UPDATE_UUID { 

P_STRING pPath; // in: Path relative to target directory. 

UUID uuid; // in/out: Application directory uuid. 

} APP DIR UPDATE UUID, *P APP DIR UPDATE UUID; 



msgAppDirGetUID 

Passes back an application directory's uid. 

Takes P_APP_DIR_UPDATE_UID, returns STATUS. 

♦define msgAppDirGetUID MakeMsg(clsAppDir, 9) 

typedef struct APP_DIR_UPDATE_UID { 

P_STRING pPath; // in: Path relative to target directory. 

UID uid; // in/out: App directory uid. 

} APP DIR UPDATE UID, *P APP DIR UPDATE UID; 
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Message 
Arguments 



msgAppDirSetUID 

Specifies an application directory's uid. 

Takes P_APP_DIR_UPDATE_UID, returns STATUS. 



tdefine msgAppDirSetUID 



MakeMsg(clsAppDir, 10) 



typedef struct APP_DIR_UPDATE_UID { 

P_STRING pPath; // in: Path relative to target directory. 

UID uid; // in/out: App directory uid. 
} APP DIR UPDATE UID, *P APP DIR UPDATE UID; 



msgAppDirGetSequence 

Passes back an application directory's sequence number. 

Takes P_APP_DIR_UPDATE_SEQ, returns STATUS. 

#define msgAppDirGetSequence MakeMsg(clsAppDir, 11) 

Arguments typedef Struct APP_DIR_UPDATE_SEQUENCE { 

P_STRING pPath; // in: Path relative to target directory. 

U32 sequence; // in/out: Application directory sequence. 

} APP_DIR_UPDATE_SEQUENCE, *P_APP_DIR_UPDATE_SEQUENCE; 

Comments If the document is in a notebook, the sequence number is a 1 -based position within the section. 

Specifies an application directory's sequence number. 

Takes P_APP_DIR_UPDATE_SEQUENCE, returns STATUS. 

#define msgAppDirSetSequence MakeMsg(clsAppDir, 12) 

Message typedef struct APP_DIR_UPDATE_SEQUENCE { 

Arguments P_STRING pPath; // in: Path relative to target directory. 

U32 sequence; // in/out: Application directory sequence. 

} APP_DIR_UPDATE_SEQUENCE, *P_APP_DIR_UPDATE_SEQUENCE; 

Comments If the document is in a notebook, the sequence number is a 1 -based position within the section. 

msgAppDirGetNumChildren 

Passes back the total number of embedded children of a document. 

Takes P_APP_DIR_UPDATE_NUM_CHILDREN, returns STATUS. 
♦define msgAppDirGetNumChildren MakeMsg(clsAppDir, 22) 

Arguments typedef struct APP_DIR_UPDATE_NUM_CHILDREN { 

P_STRING pPath; // in: Path relative to target directory. 

U32 numChildren; // in/out: App directory attr numchildren. 

} APP DIR UPDATE NUM CHILDREN, *P APP DIR UPDATE NUM CHILDREN; 



msgAppDirSetNumChildren 

Specifies the total number of embedded children of a document. 

Takes P_APP_DIR_UPDATE_NUM_CHILDREN, returns STATUS. 

tdefine msgAppDirSetNumChildren MakeMsg(clsAppDir, 23) 

Message typedef struct APP_DIR_UPDATE_NUM_CHILDREN { 

Arguments P_STRING pPath; // in: Path relative to target directory. 

U32 numChildren; // in/out: App directory attr numchildren. 

} APP DIR UPDATE NUM CHILDREN, *P APP DIR UPDATE NUM CHILDREN; 
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msgAppDirGetGlobalSequence 

Passes back an application directory's global sequence number. 

Takes P_APP_DIR_GET_GLOBAL_SEQUENCE, returns STATUS. 

tdefine msgAppDirGetGlobalSequence MakeMsg(clsAppDir, 21) 

Arguments typedef struct APP_DIR_GET_GLOBAL_SEQUENCE { 

P_STRING pPath; // in: Path relative to target directory. 

U32 globalSequence; // in/out: App directory global sequence. 

} APP_DIR_GET_GLOBAL_SEQUENCE, *P_APP_DIR_GET_GLOBAL_SEQUENCE; 

Comments The global sequence number is the 1 -based position of a document within its clsRootContainerApp 

embeddor (i.e., the document's page number in the notebook). 

msgAppDirGetBookmark 

Passes back an document's application tab. 

Takes P_APP_DIR_GET_BOOKMARK, returns STATUS. 

tdefine msgAppDirGetBookmark MakeMsg(clsAppDir, 13) 

Arguments typedef struct APP_DIR_GET_BOOKMARK { 

P_STRING pPath; // in: Path relative to target directory, 

char label [nameBuf Length] ; // out: tab label. 

} APP_DIR_GET_BOOKMARK, *P_APP_DIR_GET_BOOKMARK; 

Comments If the application directory has no tab (appDirFlags.bookmark==false), msgAppDirGetBookmark will 

return stsOK and pArgs->label will be unchanged. For this reason it is recommended that you drop a 
null byte into pArgs->label[0] before calling msgAppDirGetBookmark. Then, if the application 
directory has no tab, you will get back a null string. 



msgAppDirSetBookmark 

Specifies a document's application tab. 

Takes P_APP_DIR_SET_BOOKMARK, returns STATUS. 

#define msgAppDirSetBookmark MakeMsg(clsAppDir, 14) 

Arguments typedef Struct APP_DIR_SET_BOOKMARK { 

BOOLEAN on; // in: Turn bookmark on or off. 

P_STRING pPath; //in: Path relative to target directory, 

char label [nameBuf Length ] ; // in/out: tab label. 

} APP_DIR_SET_BOOKMARK, *P_APP_DIR_SET_BOOKMARK; 

Comments clsAppDir sends msgAppChanged to observers of clsApp as a result of this message. See app.h for a 

description of msgAppChanged. 

If label [0] is NULL, clsAppDir uses the default label, which is the name of the document. 

msgAppDirGetNextlnit 

Initializes an APP_DIR_NEXT structure. 
Takes P_APP_DIR_NEXT, returns STATUS. 

tdefine msgAppDirGetNextlnit MakeMsg (clsAppDir, 15) 

Comments Send this message to an application directory to prepare it for an ensuing msgAppDirGetNext loop. 



Arguments 



Comments 
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msgAppDirGetNext 

Passes back the attributes of the next application directory. 

Takes P_APP_DIR_NEXT, returns STATUS. 

tdefine msgAppDirGetNext MakeMsg(clsAppDir, 16) 

// out: attrs for next child. 

// out: name of next child. 

// out: fs flags for next child (see fs.h) 

// out: first app dir to examine 

// out: next app dir to examine 

// out: current app dir 
} APP_DIR_NEXT, *P_APP_DIR_NEXT; 

Send this message to an application directory in a loop to get the appDirAttrs for each embedded 
document (not recursive), ordered by sequence number. 

You generally do not change the values in the APP_DIR_NEXT structure between calls to 
msgAppDirGetNext. Doing so jeopardizes the traversal of the embedded documents. 



typedef struct 


APP 


DIR NEXT { 


APP DIR ATTRS 


attrs; 


P STRING 




pName; 


U32 




fsFlags; 


P UNKNOWN 




pFirst ; 


P UNKNOWN 




pNext ; 


P UNKNOWN 




handle; 



Message 
Arguments 



Comments 



msgAppDirReset 

Frees resources after a series of msgAppDirGetNext messages. 

Takes P_APP_DIR_NEXT, returns STATUS. 

tdefine msgAppDirReset MakeMsg(clsAppDir, 17) 



typedef struct APP_DIR_NEXT { 

APP_DIR_ATTRS attrs; 

P_STRING pName; 

U32 fsFlags; 

PJJNKNOWN pFirst; 

PJJNKNOWN pNext; 

P UNKNOWN handle; 



// out: attrs for next child. 

// out: name of next child. 

// out: fs flags for next child (see fs.h) 

// out: first app dir to examine 

// out: next app dir to examine 

// out: current app dir 



} APP DIR NEXT, *P APP DIR NEXT; 



You must send this message to the application directory after the msgAppDirGetNext loop has 
completed. Failing to do so can cause internally allocated memory not to be deallocated. 



msgAppDirSeqToName 

Passes back the name of the embedded document with a specified sequence number. 

Takes P_APP_DIR_SEQJTCLNAME, returns STATUS. 

tdefine msgAppDirSeqToName MakeMsg(clsAppDir, 18) 

Arguments typedef struct APP_DIR_SEQ_TO_NAME { 

U32 sequence; // in: Sequence number. 

P_STRING pName; // out: Buffer for name. 

// Must be nameBuf Length long. 
} APP DIR SEQ TO NAME, *P APP DIR SEQ TO NAME; 



msgAppDirGetDirectNumChildren 

Passes back the number of directly embedded documents (not recursive). 

Takes P_U32, returns STATUS. 

tdefine msgAppDirGetDirectNumChildren MakeMsg(clsAppDir, 19) 
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msgAppDirGetTotalNumChildren 

Passes back the total number of embedded documents (recursive). 

Takes P_U32, returns STATUS. 

#define msgAppDirGetTotalNumChildren MakeMsg(clsAppDir, 20) 
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APPMGR.H 



This file contains the API definition for clsAppMgr. 

clsAppMgr inherits from clsClass. 

Provides support for application classes and document management. 

"AppMgr" stands for Application Manager. 



Introduction 

When you create a new application class (i.e., install an application), rather than sending msgNew to 
clsClass you send msgNew to clsAppMgr. This allows you to specify properties of the application class, 
and also to specify in advance some default properties of the documents (i.e., instances) of the 
application class. 

There is one instance of clsAppMgr for each installed application class. This object is given the 
well-known uid of the application class. The application manager class implements document 
management messages and stores information about the installed application class in its instance data. 

tifndef APPMGR_INCLUDED 
tdefine APPMGR_INCLUDED 

#include <fs.h> 
♦include <geo.h> 

Common #defines and typedefs 

typedef OBJECT APPMGR, *P APPMGR; 



AppMgr Flags 



Various settings for the installed application class. 

stationery: If true, an instance of the application will be placed in the Stationery Notebook when the 
application is installed. The instance will have default parameters. You can also create customized 
stationery instances using the STATNRY subdirectory. See appmon.h for more details. 

accessory: If true, an instance of the application will be placed in the Accessories Palette. The instance 
will have default parameters. You can also create customized accessories instances using the ACESSRY 
subdirectory. See appmon.h for more details. 

hotMode: If true, instances of the application are created in hot mode by default. Note that you can 
change a document's hot mode flag at msglnit time (or at any other time) using msgAppSetHotMode. 
See app.h for more details. 

allowEmbedding: If true, instances of the application allow child applications to be embedded within 
them. This parameter cannot be modified on a per-document basis. 

conflrmDelete: If true, PenPoint will ask for user confirmation before deleting any instance of the 
application. This parameter cannot be modified on a per-document basis. 

deinstallable: If false, users will be prevented from deinstalling the application class. 
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systemApp: If true, users will not see the application on the list of choices for importing documents. 

lowMemoryApp: If false, users will be prevented from activating instances of the application when the 
system is low on memory. 

fullEnvironment: If true, instance of the application will have a full environment, including a 
resource list and floating window list. If false, these two items are destroyed, saving memory. In general, 
if your application does no processing in instance (i.e., it simply calls AppMonitorMain()), you should 
set fullEnvironment to false to save unneeded memory. 



typedef struct APP MGR FLAGS { 



U16 


stationery 


U16 


accessory 


U16 


hotMode 


U16 


allowEmbedding 


U16 


confirmDelete 


U16 


deinstallable 


U16 


systemApp 


U16 


lowMemoryApp 


U16 


fullEnvironment 


U16 


reservedl 


U16 


reserved2 



// Put in stationery notebook. 

// Put in accessory palette. 

// Create docs in hot mode. 

// Allow child embedded apps. 

// Confirm document deletes. 

// App class deinstallable. 

// Disable imports into this app. 

// Allow activation under low memory. 

// Initialize instance environment. 

// Reserved. 



1 
1 
1 
1 
1 
1 
1 
1 
1 
7 
16; // Reserved. 



} APP MGR FLAGS, *P APP MGR FLAGS; 



►Jr AppMgr Metrics and NEW Structure 

Public instance data for an installed application class. Also the new structure for creating a new installed 
application class. 

typedef struct APP_MGR_METRICS { 



// All fields 


are 


passed back from msgAppMgrGetMet 


rics 


!. 




// For msgNew: 


in= 


specified, out=passed back, 


na=not applicable (don't care) 


OBJECT 




dir; 




// 


na: 


App monitor dir. 


OBJECT 




appMonitor; 




// 


na: 


App monitor object 


OBJECT 




resFile; 




// 


na: 


App res file. 


OBJECT 




iconBitmap; 




// 


na: 


Icon bitmap. 


OBJECT 




smalllconBitmap; 




// 


na: 


Small icon bitmap. 


OBJECT 




appWinClass; 




// 


in: 


always clsAppWin. 


RECT32 




defaultRect; 




// 
// 


in: 


Default rectangle 
(in points) . 


char 




name [nameBuf Length] ; 




// 


na: 


Application name. 


char 




version [nameBuf Length] ; 




// 


na: 


Version. 


char 




company [nameBuf Length] ; 




// 


in: 


Company name. 


char 




de fault DocName [nameBuf Length] ; 


// 


in/out: Default 










// 




document name. 


P_STRING 




copyright; 




// 


in: 


Copyright notice. 


OS PROG HANDLE 


programHandle; 




// 


out 


: Program handle. 


U32 




reserved [4] ; 




// 


na: 


Reserved . 


APP_MGR_FLAGS 


flags; 




// 


in: 


Described above. 


} APP_MGR METRICS, 


*P_APP_MGR_METRICS , 










APP_MGR_NEW_ 


ONLS 


, *P APP MGR NEW ONLY; 











msgNew 

Install a new application class. 

Takes P_APP_MGR_NEW, returns STATUS. Category: class message. 



♦define appMgrNewFields 
classNewFields 
APP MGR NEW ONLY 



\ 
\ 
appMgr; 
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Arguments typedef struct APP_MGR_NEW { 

appMgrNewFields 
} APP_MGR_NEW, *P_APP_MGR_NEW; 

Comments The fields you commonly set are: 

pArgs->object.uid your application class's uid 

pArgs->cls.pMsg your application class's method table 

pArgs->cls.ancestor your application class's ancestor (usually clsApp) 

pArgs->cls.size size of a document's instance data 

pArgs->cls.newArgsSize size of the _NEW struct for the app class 

pArgs->appMgr.defaultRect rectangle to open doc to when floating 

pArgs->appMgr.company your company's name 

pArgs->appMgr.defaultDocName name of new documents of this application 

pArgs->appMgr. copyright copyright notice 

pArgs->appMgr.flags (see description of flags above) 

clsAppMgr objects cannot be locked, so clsAppMgr forces pArgs->object.key to 0. 



msgNewDefaults 

Initializes APP_MGR_NEW structure to default values. 

Takes P_APP_MGR_NEW, returns STATUS. Category: class message. 

typedef struct APP_MGR_NEW { 

appMgrNewFields 
} APP_MGR_NEW, *P_APP_MGR_NEW; 

Zeroes out pArgs->appMgr and sets 

pArgs->object.cap |= objCapCall | objCapSend | objCapScavenge; 

pArgs->appMgr. flags. stationery = true; 

pArgs->appMgr. flags. accessory = false; 

pArgs->appMgr.flags.allowEmbedding = true; 

pArgs->appMgr.flags.confirmDelete = true; 

pArgs->appMgr.flags.deinstallable = true; 

pArgs->appMgr. flags. sy st emApp = false; 

pArgs->appMgr.flags.hotMode = false; 

pArgs->appMgr.appWinClass = clsAppWin; 

// Default rect: 300 x 300 points, centered in theRootWindow 
WIN_METRICS wm; 

ObjCallRet (msgWinGetMetrics, theRootWindow, &wm, s) ; 
pArgs->appMgr.defaultRect.size.w = 300; 
pArgs->appMgr.defaultRect .size.h = 300; 
pArgs->appMgr.defaultRect. origin. x = (wm. bounds. size. w/2) - 

(pArgs->appMgr.defaultRect.size.w/2) 
pArgs->appMgr.defaultRect .origin. y = (wm. bounds. size. h/2) - 

(pArgs->appMgr .defaultRect . size .h/2) 
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msgAppMgrGetMetrics 

Passes back the AppMgr metrics. 

Takes P_APP_MGR_METRICS, returns STATUS. Category: class message. 

♦define msgAppMgrGetMetrics MakeMsg (clsAppMgr, 1) 

Message typedef struct APP_MGR_METRICS { 

Arguments // All fields are passed back from msgAppMgrGetMetrics. 

// For msgNew: in=specified, out=passed back, na=not applicable (don't care) 



OBJECT 


dir; 


// 


na: 


App monitor dir. 


OBJECT 


appMonitor; 


// 


na: 


App monitor object 


OBJECT 


resFile; 


// 


na: 


App res file. 


OBJECT 


iconBitmap; 


// 


na: 


Icon bitmap. 


OBJECT 


small IconBitmap ; 


// 


na: 


Small icon bitmap. 


OBJECT 


appWinClass; 


// 


in: 


always clsAppWin. 


RECT32 


defaultRect; 


// 
// 


in: 


Default rectangle 
(in points) . 


char 


name [nameBuf Length] ; 


// 


na: 


Application name. 


char 


version [nameBuf Length] ; 


// 


na: 


Version. 


char 


company [nameBuf Length] ; 


// 


in: 


Company name. 


char 


defaultDocName[nameBufLength] , 


// 


in/out: Default 






// 




document name. 


P_STRING 


copyright; 


// 


in: 


Copyright notice. 


OS PROG HANDLE 


programHandle; 


// 


out 


: Program handle. 


U32 


reserved [4] ; 


// 


na: 


Reserved . 


APP_MGR_FLAGS 


flags; 


// 


in: 


Described above. 


} APP_MGR_METRICS, 


*P_APP_MGR_METRICS , 









msgAppMgrCreate 

Creates a directory entry for a new document. 
Takes P_APP_MGR_CREATE, returns STATUS. 

♦define msgAppMgrCreate 



MakeMsg ( c 1 sAppMgr , 2 ) 



typedef struct APP_MGR_CREATE { 
FS_LOCATOR locator; 
P_STRING pName; 
U32 sequence; 
BOOLEAN renumber; 
U32 reserved [2]; 



// Parent doc. uid must be of clsAppDir. 

// in/out: Name of new app. 

// Sequence of new app in parent app. 

// true=update global sequence #s. 

// reserved. 



} APP_MGR_CREATE, *P_APP_MGR_CREATE ; 

This message transitions a document from the Non-Existent state to the Created state. 

clsAppMgr creates a new file system directory entry for the new document, using the name im pName. 
clsAppMgr also stamps the new directory with the application's class. 

If pName is pNull, clsAppMgr creates a unique name, based on the application name. If pName is not 
pNull, it points to a client-allocated buffer that must be nameBufLength bytes long. 

After msgAppMgrCreate, the document will appear in the appropriate table of contents or icon 
window. But the application instance itself will not be created until msgAppMgrActivate, which 
transitions the document from the Created state to the Activated state. 



Return Volye 



stsFSNodeNotFound Invalid pArgs->locator 
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msgAppMgrActivate § 

UI 

Activates a document. \ 

2 
Takes P_APP_MGR_ACTIVATE, returns STATUS. a 

tdefine msgAppMgrActivate MakeMsg(clsAppMgr, 3) 

Arguments typedef struct APP_MGR_ACTIVATE { 

OBJECT winDev; // Window device to activate app on. 

FS_LOCATOR locator; // Location of doc to activate. 
OBJECT parent; // Parent doc uid. 

OBJECT uid; // out: activated doc uid. 

} APP_MGR_ACTIVATE, *P_APP_MGR_ACTIVATE; 

tdefine stsAppMgrLowMemNoActivate MakeStatus (clsAppMgr, 3) 

Comments This message transitions a document from the Created or Dormant state to the Activated state. 

clsAppMgr creates a new process for the document, and a new instance of the application class in the 
new process. The Application Framework will then send the new application instance msgAppInit if the 
document was in the Created state, or msgAppRestore if the document was in the Dormant state. 

Return Voiue StsAppMgrLowMemNoActivate Document could not be activated due to low memory conditions. 

stsFSNodeNotFound Invalid pArgs->locator. 

msgAppMgrMove 

Moves a document to a new location. 

Takes P_APP_MGR_MOVE_COPY, returns STATUS. 

#define msgAppMgrMove MakeMsg (clsAppMgr, 4) 

Arguments typedef struct APP_MGR_MOVE_COPY_STYLE { 

U16 showConfirm : 1; // show confirmation UI 

U16 showProgress : 1; // show progress UI 

U16 reserved : 14; // reserved. 

U16 reserved2 : 16; // reserved. 

} APP_MGR_MOVE_COPY_STYLE, *P_APP_MGR_MOVE_COPY_STYLE ; 

typedef struct APP_MGR_MOVE_COPY { 

FS_LOCATOR locator; // Source document location. 

OBJECT source; // Source object. 

OBJECT dest; // Destination object. 

XY32 xy; // x,y location in dest object. 

CHAR name [nameBuf Length] ;// in: out New doc name; 

BOOLEAN renumber; // true=update global sequence #s. 

APP_MGR_MOVE_COPY_STYLE style; // Move/copy style. 

OBJECT appWin; // out: move/copied appwin. 

} APP_MGR_MOVE_COPY, *P_APP_MGR_MOVE_COPY; 

Comments clsAppMgr will display the appropriate UI to show the progress of any time-consuming moves. 

If the move fails due to low memory, user cancellation, etc., msgAppMgrMove will nevertheless return a 
value >= stsOK. The user will have been notified of the condition via standard error messaging facilities. 

msgAppMgrCopy 

Copies a document to a new location. 

Takes P_APP_MGR_MOVE_COPY, returns STATUS. 

tdefine msgAppMgrCopy MakeMsg (clsAppMgr, 5) 
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Message typedef Struct APP_MGR_MOVE_COPY { 

Arguments FS_LOCATOR locator; // Source document location. 

OBJECT source; // Source object. 

OBJECT dest; // Destination object. 

XY32 xy; // x,y location in dest object. 

CHAR name [nameBuf Length] ; // in: out New doc name; 

BOOLEAN renumber; // true=update global sequence #s. 

APP_MGR_MOVE_COPY_STYLE style; // Move/copy style. 

OBJECT appWin; // out: move/copied appwin. 

} APP_MGR_MOVE_COPY, *P_APP_MGR_MOVE_COPY; 

Comments clsAppMgr will display the appropriate UI to show the progress of any time-consuming copies. 

If the copy fails due to low memory, user cancellation, etc., msgAppMgrCopy will nevertheless return a 
value >= stsOK. The user will have been notified of the condition via standard error messaging facilities. 

msgAppMgrFSMove 

Low-level move message used internally by msgAppMgrMove. 

Takes P_APP_MGR_FS_MOVE_COPY, returns STATUS. Category: internal use only. 

fdefine msgAppMgrFSMove MakeMsg(clsAppMgr, 17) 

Arguments typedef struct APP_MGR_FS_MOVE_COPY { 

FS_LOCATOR source; // Source doc location. 

FS_LOCATOR dest; // Location of new parent doc. 

U32 sequence; // Sequence of new doc in parent doc. 

CHAR name [nameBuf Len gth ] ;// in/out: Name of new doc. 

U32 reserved[2]; // reserved. 

} APP_MGR_FS_MOVE_COPY, *P_APP_MGR_FS_MOVE_COPY; 

msgAppMgrFSCopy 

Low-level copy message used internally by msgAppMgrCopy. 

Takes P_APP_MGR_FS_MOVE_COPY, returns STATUS. Category: internal use only. 

#define msgAppMgrFSCopy MakeMsg(clsAppMgr, 18) 

Message typedef struct APP_MGR_FS_MOVE_COPY { 

Arguments FS_LOCATOR source; // Source doc location. 

FS_LOCATOR dest; // Location of new parent doc. 

U32 sequence; // Sequence of new doc in parent doc. 

CHAR name [nameBuf Length] ;// in/out: Name of new doc. 

U32 reserved[2]; // reserved. 

} APP_MGR_FS_MOVE_COPY, *P_APP_MGR_FS_MOVE_COPY; 

msgAppMgrDelete 

Deletes a document. 

Takes P_APP_MGR_DELETE, returns STATUS. 

#define msgAppMgrDelete MakeMsg(clsAppMgr, 6) 

Arguments typedef Struct APP_MGR_DELETE { 

FS_LOCATOR locator; // Document to delete. 

BOOLEAN renumber; // true=update global sequence #s. 

U32 reserved[2]; // reserved. 

} APP_MGR_DELETE, *P_APP_MGR_DELETE ; 

Comments This message transitions a document from the Created or Dormant state to the Non-Existent state. The 

document is deleted along with all of its directory nodes, embedded documents, document processes, 
and so on. 
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MakeMsg (clsAppMgr , 7 ) 



msgAppMgrRename 

Renames a document. 

Takes P_APP_MGR_RENAME, returns STATUS. 

♦define msgAppMgrRename 

Arguments typedef struct APP_MGR_RENAME { 

FS_LOCATOR locator; // Location of app to rename. 

P_STRING pName; // in/out: New app name. 

U32 reserved[2] ; // reserved. 

} APP_MGR_RENAME, *P_APP_MGR_RENAME ; 

Comments pName must point to a buffer nameBuflLength long. 

Return v«lue stsAppBadName Invalid new name. 

stsAppDuplicateName Name already in use. 



msgAppMgrShutdown 

Unconditionally shuts down an application instance and all children. 

Takes P_FS_LOCATOR, returns STATUS. 

tdefine msgAppMgrShutdown MakeMsg (clsAppMgr, 8) 

Comments This message transitions a document from the Activated or Opened state to the Dormant state. The 

document is not given the opportunity to veto the shutdown. The document is sent msgAppSave before 
the shutdown, so it can file its data. 



Arguments 



msgAppMgrGetRoot 

Passes back the root application (clsRootContainerApp) of a tree of applications. 
Takes P_APP_MGR_GET_ROOT, returns STATUS. 



tdefine msgAppMgrGetRoot 

typedef struct APP_MGR_GET_ROOT { 

FS_LOCATOR locator; 

char path [ f sPathBuf Length] ; 

UUID uuid; 

OBJECT app; 

U32 reserved [2]; 

} APP MGR GET ROOT, *P APP MGR GET ROOT; 



MakeMs g ( c 1 s AppMgr , 9 ) 



// Location of app. 

// out: Path to root. 

// out: Root uuid; 

// out: Root app. objNull if inactive. 

// reserved. 



msgAppMgrSetlconBitmap 

Specifies the large application icon bitmap. 
Takes OBJECT, returns STATUS. 
tdefine msgAppMgrSetlconBitmap 



MakeMs g ( c 1 s AppMgr , 10) 



msgAppMgrSetSmalllconBitmap 

Specifies the small application icon bitmap. 
Takes OBJECT, returns STATUS. 
tdefine msgAppMgrSetSmalllconBitmap 



MakeMsg (clsAppMgr, 11) 
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msgAppMgrRevert 

Reverts a document to its most recently filed copy. 

Takes P_FS_LOCATOR, returns STATUS. 

fdefine msgAppMgrRevert MakeMsg(clsAppMgr, 12) 



msgAppMgrRenumber 

Renumbers an application heirarchy. 

Takes P_FS_LOCATOR, returns STATUS. 

#define msgAppMgrRenumber MakeMsg(clsAppMgr, 13) 

The FS_LOCATOR must be a locator for a clsRootContainerApp. 



msgAppMgrDumpSubtree 

Dumps the attributes of a subtree of documents. 
Takes P_FS_LOCATOR, returns STATUS. 

tdefine msgAppMgrDumpSubtree MakeMsg(clsAppMgr, 14) 

Comments The information is output to the debug window or device. The dumped fields for each node are: 

♦ document name 

♦ UUID (low 32 bits followed by high 32 bits) 

♦ old UUID (low 32 bits followed by high 32 bits) 

♦ application class 

♦ number of children 

♦ sequence number 



msgAppMgrGetResList 

Creates a resource list, given an application UUID. 
Takes P_APP_MGR_GET_RES_LIST, returns STATUS. 
#define msgAppMgrGetResList MakeMsg(clsAppMgr, 15) 

typedef struct APP_MGR_GET_RES_LIST { 

UUID appUUID; // App uuid. 

OBJECT resList; // in/out: resource file list. 

} APP_MGR_GET_RES_LIST, *P_APP_MGR_GET_RES_LIST; 

The resource list will contain the document resource file, the application resource file, the preference 
resource file, and the system resource file. resList should be set to objNull or a well-known uid. 
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This file contains the API definition for clsAppMonitor. 

clsAppMonitor inherits from clsApp. 

Provides the standard behavior for an application's monitor object. 

You create an application monitor when you call AppMonitorMain from your main routine, when 
processCount is zero. An application monitor drives application installation and helps with 
deinstallation. It also controls displaying global application options, maintaining global state, and 
importing files. 

You should subclass clsAppMonitor if your application needs to do a more sophisticated installation 
(such as installing shared dictionaries or data files), to support file import, to set and save global 
application configurations, and to provide file converters. See the section below on Subclassing. 

dsAppMonitor's Lifecycle 

Every application has a single instance of its application monitor class alive as long as the application is 
installed. The app monitor object is owned by the application's processCount process. Clients can get 
the uid of the app monitor object by sending msgAppMgrGetMetrics to an application's class. 

clsAppMonitor is a descendant of clsApp. It makes use of the standard Application Framework lifecycle 
messages to perform some of its functions: 

msgAppInit Install the application. 

msgAppRestore Reinitialize the application after a warm-boot. 

msgAppOpenTo Display global application option sheet. 

msgAppCloseTo Take down global application option sheet. 

Note: msgAppTerminate must *never* be sent directly to the app monitor. Use msgAMTerminateOK 
and msgAMTerminate instead. 

Application Installation 

Application installation is performed as follows: 

1 . Somebody sends msglMInstall to thelnstalledApps. thelnstalledApps creates an application 
directory in the selected volume under \penpoint\sys\app, copies the application's resource file into 
the application directory, and installs the application's code. See appimgr.h for details. 

2. When the code is installed, the operating system creates the application's first process (processCount 
= 0) and begins execution of the main() routine. The application installs its classes and calls 
AppMonitorMain (). AppMonitorMain never returns; it creates the app monitor object and goes 
into an object dispatch loop (see clsmgr.h), 

3. The Application Framework sends msgAppInit to the app monitor. This initiates the app monitor's 
installation sequence. 
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4. The app monitor self sends msgAMLoadlnitDll. This causes an optional initialization .dll to be run 
and then be unloaded. 

5. The app monitor self sends msgAMPopupOptions. If a descendant wants to pop up the app 
monitor global option sheet, it must handle this message and set pArgs to true, then pass it on to its 
ancestor. This will cause the option sheet protocol (msgOptionAddCards, etc) to be sent to the app 
monitor. 

6. The app monitor self sends msgAMLoadMisc. This causes any files that the application has in the 
MISC directory to be copied into the app directory in the selected volume. 

7. The app monitor self sends msgLoadAuxNotebooks, which causes msgLoadStationery and 
msgLoadHelp to be sent to self. msgLoadStationery causes all the stationery and accessory 
templates that do not have an anmAttrNoLoad attribute on them to be loaded into the machine. 
Stationery is stored in the STATNRY directory; Accessories are stored in the ACESSRY directory. 
msgLoadHelp causes all Help Notebook documents and templates that do not have the 
anmAttrNoLoad attribute set to be loaded into the Help Notebook. 

8. The app monitor self sends msgAMLoadFormatConverters and msgAMLoadOptionalDUs. These 
messages are currently not implemented by clsAppMonitor; descendants can deal with them if 
desired. There might be default superclass behavior in the future. 

Stationery, Accessory, and Help Documents 

Stationery and Accessory documents can either be saved document instances (typically copied out to a 
distribution disk with the Connections Notebook), or plain directories containing files that the 
application knows about. 

Help documents can be directories containing ASCII or RTF files, or PenPoint documents. 

These items must be located in the application's installation directory in subdirectories called 
STATNRY, ACCESSRY, and HELP. 

Subclassing clsAppMonitor 

The app monitor is an excellent place to add global application control and syncronization functions, 
since it is always around and easily accessable. For instance, if an application wants its documents to 
access some application-specific shared data (such as a list of worldwide telephone country codes), the 
app monitor for the application could manage this data and provide an API to access it. 

Applications can have a global application option sheet automatically displayed when the application is 
installed by handling msgAMPopupOptions. A special resource is written into the application's resource 
file after this occurs, inhibiting subsequent popups if the resource file is copied to the application's 
installation directory. clsAppMon does not provide any default cards; you must provide at least one if 
you handle msgAMPopupOptions. 

If you display a user interface from your app monitor you will probably have to turn on the 
fullEnvironment app manager flag when you create your main application class. If this flag is false then 
the app monitor will run in a stripped down process environment. This saves a substantial amount of 
memory, but does not have process-local resources such as theProcessResList. 

If you subclass clsAppMonitor, you must specify your descendant's class name when you call 
AppMonitorMain. The first parameter to this routine is the global well-known name of your application 
class. The second is the global well-known name of your descendant of clsAppMonitor. If you do not 
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subclass clsAppMonitor, pass objNull for the second parameter. The AppMonitorMain routine will 
know to create a default application monitor. 



#ifndef APPMON_INCLUDED 
tdefine APPMON_INCLUDED 

tifndef FS_INCLUDED 

tinclude <fs.h> 

tendif 

tifndef OPTION_INCLUDED 

tinclude <option.h> 

tendif 



f Common #defines and typedefs 



This attribute represents the last modified date that a piece of stationery had when it was installed on 
the machine. 



tdefine amAttrDateTimeLoaded 



FSMakeFix32Attr (clsAppMonitor, 2) 



Application Framework Messages 



msgAppInit 

Installs the application. 

Takes DIR.HANDLE, returns STATUS. 

Comments This message is sent once and only once by the system, when the application is first installed from disk. 

The app monitor initializes its instance data, runs the installation protocol (msgAMLoadlnitDLL, 
msgAMLoadStationery, msgAMLoadMisc, etc), adds this application to system lists, and signals the 
installation process to continue running. 

Descendants: You can handle this message to perform any first-time initialization. The ancestor must be 
called before your handler. 

msgAppRestore 

Reinitializes the application after a warm-boot. 

Takes nothing, returns STATUS. 

Comments This message is sent by the system when a warm-boot occurs. The app monitor initializes its instance 

data and signals the system warm-boot process to proceed. 

Descendants: You can handle this message and perform any first-time initialization. The ancestor must 
be called before your handler. 

msgAppOpen 

Displays the global configuration option sheet. 

Takes P_APP_OPEN, returns STATUS. 

Comments This message is self-sent by msgAMPopupOptions. It can also be sent by anyone else. 

The app monitor displays the application configuration option sheet (tagAppDocOptSheet). 

Descendants: You normally do not handle this message. To provide an option sheet, see 
msgAMPopupOptions. 
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msgAppClose 

Removes the global configuration option sheet. 

Takes nothing, returns STATUS. 

This message is self-sent by msgAMPopupOptions. It can also be sent by anyone else. 

Descendants: You normally do not handle this message. 



Import Messages 



msglmportQueiy 

Determines if a file can be imported by the application. 

Takes P_IMPORT_QUERY, returns STATUS. 

Comments The app monitor forwards msglmportQuery to its class as a class message. If it isn't handled there, the 

app monitor sends back "No" to all import requests. In the future there will be support to run through 
any of the file translators that the application has loaded. 

Descendants: You normally do not handle this message. 

See Also import.h 



msglmport 

Imports a file. 

Takes P_IMPORT_DOC, returns STATUS. 

Comments The app monitor first creates a new document object and activates it. It then forwards msglmport to 

the document. Next, it sends msgAppMgrShutdown to both save the document and shut it down. 

Descendants: You normally do not handle this message. 

See Also import.h 

App Monitor Messages 



msgAMGetMetrics 

Gets the app monitor's metrics. 

Takes P_AM_METRICS, returns STATUS. 

tdefine msgAMGetMetrics MakeMsg(clsAppMonitor, 1) 

Arguments typedef Struct AM_METRICS { 

CLASS appClass; // Main application class. 

OBJECT handle; // This app' s handle in thelnstalledApps . 

U32 unused2; 

U32 unused3; 

U32 unused4; 

U16 unused; 

} AM_METRICS, *P_AM_METRICS; 

Comments Descendants: You normally do not handle this message. 
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msgAMGetlnstallDir 

Creates a directory handle on the application's installation directory. 

Takes P_OBJECT, returns STATUS. 

♦define msgAMGetlnstallDir MakeMsg(clsAppMonitor, 2) 

Comments The app monitor creates a clsDirHandle object which references the location on external media that the 

application was installed from. If the external volume is not connected, the user is asked to attach it. 

If this application was bundled with PenPoint then there is no valid external volume beyond installation 
time. stsFailed is returned in this case. 

NOTE: CALLER IS RESPONSIBLE FOR DESTROYING THE DIR HANDLE WHEN DONE. 

Return Value stsOK The external volume is attached. The user tapped the Cancel button when 

promptedto attach the external volume. The external volume cannot be determined 

becausethis application was bundled with PenPoint. 

Descendants: You normally do not handle this message. 



2 



msgAMLoadlnitDU 

Loads, runs, and unloads an optional dll initialization routine. 

Takes OBJECT, returns STATUS. 

♦define msgAMLoadlnitDU MakeMsg(clsAppMonitor, 4) 

Comments The app monitor looks for an init.dll file in the applications directory (which is specified in pArgs). If it 

is found, the DllMain routine for this dll is run. The dll is then unloaded. 

Descendants: You normally do not handle this message. 

Return Value stsOK Either the dll initialization was not found or it was found andrun successfully. 
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msgAMLoadMisc 

Load the application's miscellaneous files. 
Takes nothing, returns STATUS. 

tdefine msgAMLoadMisc MakeMsg(clsAppMonitor, 5) 

Comments If a directory called MISC exists, the app monitor copies this directory into the in-memory application 

directory. 

Descendants: You normally do not handle this message. However, you can create the MISC directory 
and place in it files that all of your documents need to use. For example, your documents may need to 
reference a file that contains all of the postal/zip codes for a country. 

Return Volwe stsOK Either the MISC directory was not found or wasfound and copied successfully. 



msgAMLoadStationery 

Loads stationery and accessory templates. 
Takes nothing, returns STATUS. 
tdefine msgAMLoadStationery 



MakeMsg(clsAppMonitor, 6) 
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Comments The app monitor looks for stationery in a directory named STATNRY and accessories in a directory 

named ACCESSRY in the app's directory. It copies any templates that are not marked with the noLoad 
attribute from these directories to the Stationery and Accessories notebooks. 

A template is a subdirectory with a either a complete, saved document or any kind of file that the 
application can read. 

If appMgrMetrics.flags.stationery is true, the app monitor creates a default piece of stationery (an 
empty document of its application type). Similarly, if appMgrMetrics.flags.accessory is true, the app 
monitor places an empty document in the Accessories notebook. 

Descendants: You normally do not handle this message. 



msgAMRemoveStationery 

Removes all the stationery and accessory templates for this application. 

Takes nothing, returns STATUS. 

♦define msgAMRemoveStationery MakeMsg(clsAppMonitor, 7) 

Comments The app monitor removes the stationery notebook section for this application, which removes the 

stationery loaded in msgAMLoadStationery and any user- defined stationery. It then removes all of this 
application's documents from the Accessories notebook (thereby removing templates loaded in 
msgAMLoadStationery and any documents that the user placed there). 

Descendants: You normally do not handle this message. 

msgAMLoadHelp 

Loads the application's help into the Help Notebook. 

Takes nothing, returns STATUS. 

♦define msgAMLoadHelp MakeMsg(clsAppMonitor, 8) 

Comments The app monitor looks for a HELP subdirectory in the application's directory. If HELP exists, the app 

monitor copies all of the help templates that are not marked with the noLoad attribute to the Help 
Notebook. Help templates can be directories with ASCII, RTF or saved MiniText documents in them. 

Descendants: You normally do not handle this message. 

msgAMRemoveHelp 

Removes all Help Notebook items for this application. 
Takes nothing, returns STATUS. 

♦define msgAMRemoveHelp MakeMsg(clsAppMonitor, 9) 

Comments The app monitor removes all of this application's items from the Help Notebook. 

Descendants: You normally do not handle this message. 

msgAMPopupOptions 

Pops up a global option sheet the first time the app is installed. 

Takes P_BOOLEAN, returns STATUS. 

♦define msgAMPopupOptions MakeMsg(clsAppMonitor, 17) 
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Comments If pArgs is false, the app monitor does not do anything. If it is true, the app monitor pops up the global 

option sheet, then writes a resource in the application's resource file which inhibits subsequent popups. 

Descendants: If you want to allow the user to configure (or check the configuration of) the application 
as it is being installed, you need to handle this message. In your handler, you should set pArgs to true 
and then call the ancestor. You also need to create an option sheet resource with a tag of 
tagAppDocOptSheet (in your application's msgAppAddCards handler). 

You can have the option sheet to always pop up (even after the first time the user installs the application) 
by not calling the ancestor and popping up the option sheet yourself with: 

ObjCallRet(msgAppOpenTo, self, (P_ARGS) appOpenToFloating, s); 



« 



Comments 



msgAMLoadAuxNotebooks 

Loads items into auxilliary notebooks. 

Takes nothing, returns STATUS. 

tdefine msgAMLoadAuxNotebooks MakeMsg(clsAppMonitor, 14) 

The app monitor self sends msgAMLoadStationery and msgAmLoadHelp to load the application's 
stationery, accessory, and help templates. 

Descendants: You normally do not handle this message. 



msgAMLoadFormatConverters 

Loads file format converter .dlls. 
Takes nothing, returns STATUS. 

tdefine msgAMLoadFormatConverters MakeMsg(clsAppMonitor, 10) 

Comments Currently, the app monitor does not do anything in response to this message. It will do something in the 

future. 

Descendants: You normally do not handle this message. 

msgAMUnloadFormatConverters 

Unloads file format converter .dlls. 

Takes nothing, returns STATUS. 

#define msgAMUnloadFormatConverters MakeMsg(clsAppMonitor, 11) 

Comments Currently, the app monitor does not do anything in response to this message. It will do something in the 

future. 

Descendants: You normally do not handle this message. 



Comments 



msgAMLoadOptionalDlls 

Loads an application's optional .dlls. 

Takes nothing, returns STATUS. 

♦define msgAMLoadOptionalDlls MakeMsg(clsAppMonitor, 12) 

Currently, the app monitor does not do anything in response to this message. It will do something in the 
future. 

Descendants: You normally do not handle this message. 
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msgAMUnloadOptionalDlls 

Unloads an application s optional .dlls. 

Takes nothing, returns STATUS. 

#define msgAMUnloadOptionalDlls MakeMsg(clsAppMonitor, 13) 

Currently, the app monitor does not do anything in response to this message. It will do something in the 
future. 



Descendants: You normally do not handle this message. 



msgAMTerminateOK 

Asks if this application is willing to terminate. 

Takes P_OBJECT, returns STATUS. 

tdefine msgAMTerminateOK MakeMsg(clsAppMonitor, 20) 

Comments Deinstallation is a two phase process. All applications and services that are to be deinstalled together get 

the chance to veto. This message is sent to an application monitor to see if it wishes to veto. 

By default, the app monitor unconditionally terminates all of its application s instances. To do so, it 
sends msgAppMgrShutdown to its application class for each of its active documents. 

Descendants: If you want to be given the chance to terminate the application, you should handle this 
message. In your handler, if you decide that you want to terminate, you simply pass the message on to 
your ancestor. 

You can veto the termination by returning anything other than stsOK and by not passing the message 
on to your ancestor. If you veto, you must set pArgs to the uid of the object that was responsible for the 
veto, which is typically self. 

See Also msgAMTerminate 



msgAMTerminate 

Terminates this application. 

Takes nothing, returns STATUS. 

#define msgAMTerminate MakeMsg(clsAppMonitor, 21) 

lomments Deinstallation is a two phase process. All applications and services that are to deinstalled together get the 

chance to veto. This message is sent to an application monitor after everyone has agreed to the 
deinstallation. 

This message unconditionally terminates the application in the final phase of deinstallation. The app 
monitor self sends msgAMRemoveStationery and msgAMRemoveHelp, and then calls 
OSTaskTerminate to kill the application's processCount task. 

Descendants: You should handle this message to remove anything you have loaded. The ancestor must 
be called after your handler. 

lee Also msgAMTerminateOK 
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msgAMTerminateVetoed § 

in 

Sent when the application termination sequence is vetoed. 

Takes P_AM_TERMINATE_VETOED, returns STATUS. 

Idefine msgAMTerminateVetoed MakeMsg(clsAppMonitor, 22) 

Arguments typedef Struct AM_TERMINATE_VETOED { 

OBJECT vetoer; // Object or class that vetoed the deinstallation. 

STATUS status; // Veto status. 

} AM_TERMINATE_VETOED, *P_AM_TERMINATE_VETOED ; 

Comments When one of the applications or services that are deinstalled together vetoes termination, the 

Application Framework sends this message to those applications and services. 

pArgs->vetoer gives the uid of the object or class that vetoed the deinstallation. pArgs->status gives the 
return status of the veto. The app monitor does not do anything in response to this message. 

Descendants: You can handle this message if you wish. If you handled msgTerminateOK, and changed 
anything because you thought you were about to be terminated, you should handle this message to 
change things back to the way they were. 

See Also msgAMTerminateOK 



tdefine tagAMFirstTime MakeTag(clsAppMonitor, 2) 
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This file contains constant tags used by the Application Framework. 
There are three kinds of tags in this file: 

♦ Resource tags 

♦ Window tags 

♦ Quick help tags 

Resource tags are used to construct resource identifiers (resID's) that identify well-known resources in 
the system resource file. Developers can use these tags to read a copy of any of these resources from their 
document's resList (see app.h and resfile.h). 

Window tags are used as arguments to msgWinFindTag to locate well-known windows. For example, all 
the standard application menus (SAMS) are tagged so they can be programatically located and changed 
or removed by an application. 

Quick help tags are used for two purposes: (1) to construct the resource identifier used to read a 
quick-help string from the document's resList, and (2) stored in clsGWin as the quick-help tag (see 
gwin.h). 

All the resource ids in this file are constructed by (see resfile.h): 

MakeWknRes Id (resld, appResId, tag); 

To write an object resource: 

write. resld = tagAppObject; 

write. mode = resWriteObjectOnce; 

write. object = object ToWrite; 

ObjCallRet (msgResWriteObject, file, fcwrite, s) ; 

To read an object resource: 

ObjectCall(msgNewDefaults, clsObject, Sread.new); 

read. resld = tagAppObject; 

read. mode = resReadObjectOnce; 

ObjCallRet (msgResReadObject, resList, &read, s); 

newObject = read . new . uid; 

tifndef APPTAG_INCLUDED 
tdefine APPTAG_INCLUDED 

Resource Tags 

dsApp Resource Identifiers 

Used to construct Application Framework resID's (see above). 

tdefine appResId MakeTag(clsApp, 1) 

// next: 194 
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Tags used by StdMsg. 

♦define tagAppDeleteRequest 
tdefine tagAppDeleteSectRequest 
tdefine tagAppRevertRequest 
♦define tagAppSystemShutdownRequest 
♦define tagAppSystemSoftShutdownRequest 



MakeDialogTag(clsAppMgr, 0) 
MakeDialogTag(clsAppMgr, 1) 
MakeDialogTag(clsAppMgr, 2) 
MakeDialogTag(clsAppMgr, 3) 
MakeDialogTag(clsAppMgr, 4) 



Miscellaneous tags. 

tdefine tagAppObject 
tdefine tagAppClass 
tdefine tagAppQHAppClass 
tdefine tagAppTitleBar 
tdefine tagAppMovelconMarquee 
tdefine tagAppCopylconMarguee 
tdefine tagAppPrintMetrics 
tdefine tagAppMenuImport 
tdefine tagAppMenuExport 

These identify each item in the SAMS menu bar. 

tdefine tagAppMenuBar 
tdefine tagAppMenuDocument 
tdefine tagAppMenuEdit 
tdefine tagAppMenuOptions 
tdefine tagAppMenuCreate 

These identify each item in the Document menu. 

tdefine tagAppMenuCheckpoint 
tdefine tagAppMenuRevert 
tdefine tagAppMenuPrint 
tdefine tagAppMenuPrintSetup 
tdefine tagAppMenuSend 
tdefine tagAppMenuAbout 

These identify each item in the Edit menu. 

tdefine tagAppMenuUndo 
tdefine tagAppMenuSelectAll 
tdefine tagAppMenuMove 
tdefine tagAppMenuCopy 
tdefine tagAppMenuDelete 
tdefine tagAppMenuSearch 
tdefine tagAppMenuSpell 

These identify SAMS option sheets. 

tdefine tagAppAboutOptSheet 
tdefine tagAppDocOptSheet 
tdefine tagAppPrintSetupOptSheet 
tdefine tagAppIconOptSheet 

These identify each card in the Document option sheet. 

tdefine tagAppOptControlsCard 
tdefine tagAppOptAccessCard 
tdefine tagAppOptCommentsCard 
tdefine tagAppOptlconCard 
tdefine tagAppOptGotoButtonCard 
tdefine tagAppOptlconWinCard 

These identify each card in the About option sheet. 

tdefine tagAppOptlnfoCard 
tdefine tagAppOptAboutCard 
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MakeTag (clsApp, 123) 
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MakeTag (clsApp, 144) 

MakeTag (clsApp, 147) 

MakeTag (clsApp, 154) 

MakeTag (clsApp, 172) 



MakeTag (clsApp, 140) 
MakeTag (clsApp, 141) 



These identify each card in the Print Setup option sheet. 



♦define tagAppOptPrintCard 
♦define tagAppOptHeadersCard 
♦define tagAppOptEmbeddeeCard 

These identify each item in the Borders & Controls card. 

♦define tagAppOptCtrls 
♦define tagAppOptCtrlsLabel 
♦define tagAppOptCtrlsOn 
♦define tagAppOptCtrlsOff 
♦define tagAppOptCtrlStyle 
♦define tagAppOptCtrlStyleLabel 
♦define tagAppOptCtrlTitleBar 
♦define tagAppOptCtrlMenuBar 
♦define tagAppOptCtrlScrollBars 
♦define tagAppOptCtrlCorkMargin 
♦define tagAppOptBorderStyle 
♦define tagAppOptBorderStyleLabel 
♦define tagAppOptBorderSingle 
♦define tagAppOptBorderDouble 
♦define tagAppOptBorderDashed 
♦define tagAppOptBorderNone 

These identify each item in the Access card. 

♦define tagAppOptDelete 
♦define tagAppOptDeleteLabel 
♦define tagAppOptDeleteOn 
♦define tagAppOptDeleteOff 
♦define tagAppOpt Readonly 
♦define tagAppOptReadOnlyLabel 
♦define tagAppOptReadOnlyOn 
♦define tagAppOptReadOnlyOff 
♦define tagAppOptHotMode 
♦define tagAppOptHotModeLabel 
♦define tagAppOptHotModeOn 
♦define tagAppOptHotModeOff 

These identify each item in the Comments card. 

♦define tagAppOptCommentsTable 
♦define tagAppOptTitle 
♦define tagAppOptTitleLabel 
♦define tagAppOpt Author 
♦define tagAppOpt AuthorLabel 
♦define tagAppOpt Comments 
♦define tagAppOptCommentsSWin 
♦define tagAppOpt Comments Label 

These identify each item in the About/Document card. 

♦define tagAppOptCreated 
♦define tagAppOptCreatedLabel 
♦define tagAppOptModified 
♦define tagAppOptModifiedLabel 
♦define tagAppOptFiledSize 
♦define tagAppOptFiledSizeLabel 
♦define tagAppOptActiveSize 
♦define tagAppOptActiveSizeLabel 

These identify each item in the About/Application card. 

♦define tagAppOptApp 
♦define tagAppOptAppLabel 
♦define tagAppOptVersion 
♦define tagAppOptVersionLabel 
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tdefine tagAppOpt Company 

♦define tagAppOptCompanyLabel 

tdefine tagAppOptCopyright 

#define tagAppOptCopyrightLabel 

tdefine tagAppdptlcon 

tdefine tagAppOpt I conLabel 

tdefine tagAppOptlconSmall 

tdefine tagAppOptlconSmallLabel 

These identify each item in the Icon Window Layout card. 

tdefine tagAppIconWinLayout 

tdefine tagAppIconWinLayoutLabel 

tdefine tagAppIconWinTToB 

tdefine tagAppIconWinBToT 

tdefine tagAppIconWinUnconstrained 

tdefine tagAppIconWinStyle 

tdefine tagAppIconWinStyleLabel 

tdefine tagAppIconWinKeepSame 

tdefine tagAppIconWinOpenlnPlace 

These identify each item in the Print Setup cards. 

tdefine tagAppPaperSize 

tdefine tagAppPaperSizeLabel 

tdefine tagAppPaperWidth 

tdefine tagAppPaperHeight 

tdefine tagAppTopMargin 

tdefine tagAppTopMarginLabel 

tdefine tagAppBottomMargin 

tdefine tagAppBottomMarginLabel 

tdefine tagAppLeftMargin 

tdefine tagAppLeftMarginLabel 

tdefine tagAppRightMargin 

tdefine tagAppRightMarginLabel 

tdefine tagAppLeftHeader 

tdefine tagAppLeftHeaderLabel 

tdefine tagAppCenterHeader 

tdefine tagAppCenterHeaderLabel 

tdefine tagAppRightHeader 

tdefine tagAppRightHeaderLabel 

tdefine tagAppLeftFooter 

tdefine tagAppLeftFooterLabel 

tdefine tagAppCenterFooter 

tdefine tagAppCenterFooterLabel 

tdefine tagAppRightFooter 

tdefine tagAppRightFooterLabel 

tdefine tagAppEmbedVisible 

tdefine tagAppEmbedVisibleLabel 

tdefine tagAppOrientation 

tdefine tagAppOrientationLabel 

tdefine tagAppHeaderMargin 

tdefine tagAppHeaderMarginLabel 

tdefine tagAppFooterMargin 

tdefine tagAppFooterMarginLabel 

tdefine tagAppHeaderFont 

tdefine tagAppHeaderFontLabel 

tdefine tagAppHeaderSize 

tdefine tagAppHeaderSizeLabel 

tdefine tagAppFirstPage 

tdefine tagAppFirstPageLabel 

tdefine tagAppOtherLabel 

tdefine tagAppEmbedLoc 

tdefine tagAppEmbedLocLabel 

tdefine tagAppEmbedApplyTo 

tdefine tagAppHeaderMarginOtherButton 
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♦define tagAppHeaderMarginOtherField 
♦define tagAppFooterMarginOtherButton 
♦define tagAppFooterMarginOtherField 
♦define tagAppTopMarginOtherButton 
♦define tagAppTopMarginOtherField 
♦define tagAppBottomMarginOtherButton 
♦define tagAppBottomMarginOtherField 
♦define tagAppLeftMarginOtherButton 
♦define tagAppLeftMarginOtherField 
♦define tagAppRightMarginOtherButton 
♦define tagAppRightMarginOtherField 
♦define tagAppEmbedApplyToLabel 

These identify each item in the Icon option card. 

♦define tagAppIconTitle 

♦define tagAppIconTitleLabel 

♦define tagAppIconOpen 

♦define tagAppIconOpenLabel 

♦define tagAppIconOpenlnPlace 

♦define tagAppIconOpenFloating 

♦define tagAppIconType 

♦define tagAppIconTypeLabel 

♦define tagAppIconTypePictAndTitle 

♦define tagAppIconTypePictOnly 

♦define tagAppIconTypeSmallPictAndTitle 

♦define tagAppIconTypeSmlPictOverTitle 

♦define tagAppIconTypeSmallPictOnly 

These identify each item in the Goto Button option card. 

♦define tagAppGotoButtonTitle 
♦define tagAppGotoButtonTitleLabel 
♦define tagAppGotoButtonTargetDoc 
♦define tagAppGotoButtonTargetDocLabel 
♦define tagAppGotoButtonBorderLabel 
♦define tagAppGotoButtonBorder 
♦define tagAppGotoButtonSquare 
♦define tagAppGotoButtonRound 
♦define tagAppGotoButtonHRound 
♦define tagAppGotoButtonNone 

These identify various bitmaps. 

♦define tagAppIconBitmap 
♦define tagAppSmalllconBitmap 
♦define tagAppDefaultDodconBitmap 
♦define tagAppDefaultDocSmalllconBitmap 
♦define tagAppMovelconBitmap 
♦define tagAppCopylconBitmap 
♦define tagAppLinklconBitmap 
♦define tagAppClosedFolderBitmap 
♦define tagAppClosedFolderSmBitmap 
♦define tagAppOpenFolderBitmap 
♦define tagAppOpenFolderSmBitmap 





APPTAG.H 141 






Resource Tags 




MakeTag (clsApp, 


178) 


O 


MakeTag (clsApp, 


179) 


MakeTag (clsApp, 


180) 


Ul 


MakeTag (clsApp, 


181) 


2 


MakeTag (clsApp, 


182) 


Ik 


MakeTag (clsApp, 


183) 


a. 


MakeTag (clsApp, 


184) 


**> 


MakeTag (clsApp, 


185) 


c* 


MakeTag (clsApp, 


186) 




MakeTag (clsApp, 


187) 




MakeTag (clsApp, 


188) 




MakeTag (clsApp, 


192) 




MakeTag (clsApp, 


105) 




MakeTag (clsApp, 


106) 




MakeTag (clsApp, 


107) 




MakeTag (clsApp, 


108) 




MakeTag (clsApp, 


109) 




MakeTag (clsApp, 


110) 




MakeTag (clsApp, 


111) 




MakeTag (clsApp, 


112) 




MakeTag (clsApp, 


113) 




MakeTag (clsApp, 


114) 




MakeTag (clsApp, 


115) 




MakeTag (clsApp, 


116) 




MakeTag (clsApp, 


117) 




MakeTag (clsApp, 


150) 




MakeTag (clsApp, 


151) 




MakeTag (clsApp, 


152) 




MakeTag (clsApp, 


153) 




MakeTag (clsApp, 


154) 




MakeTag (clsApp, 


155) 




MakeTag (clsApp, 


156) 




MakeTag (clsApp, 


157) 




MakeTag (clsApp, 


158) 




MakeTag (clsApp, 


159) 




MakeTag (clsApp, 


15) 




MakeTag (clsApp, 


16) 




MakeTag (clsApp, 


17) 




MakeTag (clsApp, 


18) 




MakeTag (clsApp, 


19) 




MakeTag (clsApp, 


20) 




MakeTag (clsApp, 


21) 




MakeTag (clsApp, 


22) 




MakeTag (clsApp, 


23) 




MakeTag (clsApp, 


24) 




MakeTag (clsApp, 


25) 





Tags used during the creation of a document to get default values for some fields from the application 
resource file. 



♦define tagAppMgrDe fault DocName 
♦define tagAppMgrDisplayedAppName 



MakeTag (clsApp, 189) 
MakeTag (clsApp, 193) 
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APPWIN.H 



This file contains the API definition for clsAppWin. 
clsAppWin inherits from clsCustomLayout. 
Provides support for embedded applications. 
"AppWin" stands for Application Window. 



Introduction 



clsAppWin is an embedded window that manages an embedded document. It shrink-wraps around a 
clslcon object to display an icon to the user, like those on the bookshelf or embedded in a document. 
When an icon with style awOpenlnPlace is tapped, the application window destroys the icon and opens 
the associated document into itself. The application window then shrink-wraps around the document's 
main window. 

Application Windows live in the process space and are filed with the embeddor document. 

An application window reads its icon bitmap from metrics.resList of OSThisAppQ in response to 
msglconProvideBitmap (see icon.h). It uses the following resID (see apptag.h): 

MakeWknResIdX(read.resId, appResId, tagAppIconBitmap) / 

This bitmap is usually found in the app.res file of the application class for the associated document. The 
document can override this bitmap by filing a resource with the above resld into its doc.res file. 

AppWins can also store their own private bitmaps. Use msgAppWinSetlconBitmap to give an 
application window a bitmap. This bitmap object will be filed by the application window. If an 
application window has its own bitmap object, it will not read from the resList. 

tifndef APPWIN_INCLUDED 
#define APPWIN_INCLUDED 

tifndef CLAYOUT_INCLUDED 
tinclude <clayout.h> 
#endif 



Common #defines and typedefs 

typedef OBJECT APP_WIN, *P_APP_WIN; 

Application Window States 

These are the valid states for an application window. 

#define awClosed 

tdefine awOpenedFloating 1 

#define awOpenedlnPlace 2 

tdefine awOpenedlnPlaceFloating 3 
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Application Window Open Styles 

These are the valid styles for directing an application window how to open. 

#define awOpenlnPlace 

tdefine awOpenFloating 1 

Application Window Icon Types 

These are the valid icon types. 

tdefine awPictAndTitle 

tdefine awPictOnly 1 

#define awSmallPictAndTitle 2 

#define awSmallPictOnly 3 

#define awSmallPictOverTitle 4 

Application Window Style Structure 

This structure defines the various application window styles. 



typedef struct APP_WIN_STYLE { 
U16 open 
U16 type 

U16 openStyleLock 
U16 privatel 
U16 private2 
U16 reserved 



2; // Open style. 

4; // Icon type. 

1; // True = cannot change open style 

1; // Reserved. 

1; // Reserved. 

7; // Reserved. 



} APP_WIN_STYLE, *P_APP_WIN_STYLE; 

Messages 



msgNew 

Creates a new Application Window. 

Takes P_APP_WIN_NEW, returns STATUS. Category: class message. 

typedef struct APP WIN NEW ONLY { 



UUID 


appUUID; 


// App uuid. 


APP WIN STYLE 


style; 


// Application Window style 


U16 


state; 


// Application Window state 


char 


label [nameBuf Length] ; 


// Icon label. 


U32 


reserved [4] ; 


// Reserved. 



} APP_WIN_NEW_ONLY, *P_APP_WIN_NEW_ONLY; 

♦define appWinNewFields \ 
customLayoutNewFields \ 
APP_WIN_NEW_ONLY appWin; 

typedef struct APP_WIN_NEW { 

appWinNewFields 
} APP WIN NEW, *P APP WIN NEW; 



msgNewDefaults 

Initializes the APP_WIN_NEW structure to default values. 

Takes P_APP_WIN_NEW, returns STATUS. Category: class message. 



fttessoga typedef struct APP_WIN_NEW { 

Arguments appWinNewFields 

} APP WIN NEW, *P APP WIN NEW; 



Comments 
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Messages 




>es out pArgs->appWin and sets 






* 




pArgs->win . flags . style 

pArgs->win . flags . input 
pArgs->embeddedWin . style . embeddee 


|= wsCaptureGeometry 
I wsSendGeometry 
I wsShrinkWrapWidth 
I wsShrinkWrapHeight; 

|= inputHoldTimeout; 
= true; 






s 

111 

21 

u. 

a 
a 
< 


pArgs->erabeddedWin . style .moveable 


= true; 








pArgs->embeddedWin . style . copyable 
pArgs->border . style .previewAlter 
pArgs->border . style . selectedAlter 


= true; 

= bsAlterNone; 

= bsAlterNone; 






pArgs->appWin . style . open 
pArgs->appWin . style . type 
pArgs->appWin . state 


= awOpenlnPlace; 

= awSmallPictAndTitle; 

= awClosed; 









msgAppWinGetMetrics 

Passes back an application window's metrics. 

Takes P_APP_WIN_METRICS, returns STATUS. 

tdefine msgAppWinGetMetrics MakeMsg(clsAppWin, 1) 



typedef struct APP WIN METRICS { 



UUID 


appUUID; 


OBJECT 


icon; 


OBJECT 


iconBitmap; 


OBJECT 


smalllconBitmap; 


OBJECT 


appClass; 


APP WIN STYLE 


style; 


U16 


state; 


char 


label [nameBuf Length] ; 


U32 


reserved [4] ; 



// Application uuid. 

// Application Window icon. 

// Icon bitmap. 

// Small icon bitmap. 

// Application class. 

// Application Window style. 

// Application Window state. 

// Icon label. 

// Reserved. 



Comments 



} APP_WIN_METRICS, *P_APP_WIN METRICS; 

msgAppWinGetState 

Passes back an application window's state. 

Takes P_U16, returns STATUS. 

tdefine msgAppWinGetState MakeMsg(clsAppWin, 2) 

Possible values are described in Application Window States, above. 



"©mmesifs 



msgAppWinSetState 

Specifies an application window's state. 

Takes U16, returns STATUS. 

tdefine msgAppWinSetState MakeMsg(clsAppWin, 3) 

Possible values are described in Application Window States, above. 



msgAppWinGetStyle 

Passes back an application window's style. 
Takes P_APP_WIN_STYLE, returns STATUS. 
tdefine msgAppWinGetStyle 



MakeMsg (clsAppWin, 4 ) 
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typedef struct APP_WIN_STYLE { 



U16 open 

U16 type 

U16 openStyleLock 

U16 privatel 

U16 private2 

U16 reserved 



// Open style. 

// Icon type. 

// True = cannot change open style. 

// Reserved. 

// Reserved. 

// Reserved. 



} APP_WIN_STYLE, *P_APP_WINJSTYLE; 

msgAppWinSetStyle 

Specifies an application window's style. 
Takes APP_WIN_STYLE, returns STATUS. 
tdefine msgAppWinSetStyle 



MakeMsg(clsAppWin, 5) 



typedef struct APP_WIN_STYLE { 



U16 open 

U16 type 

U16 openStyleLock 

U16 privatel 

U16 private2 

U16 reserved 



// Open style. 

// Icon type. 

// True = cannot change open style. 

// Reserved. 

// Reserved. 

// Reserved. 



} APP_WIN_STYLE, *P_APP_WIN STYLE; 

msgAppWinSetLabel 

Specifies an application window's label. 
Takes P_STRING, returns STATUS. 
#define msgAppWinSetLabel 

msgAppWinSetlconBitmap 

Specifies an application window's large icon bitmap. 

Takes BITMAP, returns STATUS. 

tdefine msgAppWinSetlconBitmap MakeMsg(clsAppWin, 7) 



MakeMsg(clsAppWin, 6) 



msgAppWinSetSmalllconBitmap 

Specifies an application window's small icon bitmap. 

Takes BITMAP, returns STATUS. 

tdefine msgAppWinSetSmalllconBitmap MakeMsg(clsAppWin, 8) 



msgAppWinOpen 

Opens the document associated with an application window. 

Takes nothing, returns STATUS. 

tdefine msgAppWinOpen MakeMsg(clsAppWin, 9) 

msgAppWinClose 

Closes the document associated with an application window. 

Takes nothing, returns STATUS. 

tdefine msgAppWinClose MakeMsg(clsAppWin, 10) 
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msgAppWinDelete 

Deletes an application window. 

Takes BOOLEAN, returns STATUS. 

#define msgAppWinDelete MakeMsg(clsAppWin, 11) 

Comments If pArgs is true, msgAppWinDelete also deletes the associated document. If pArgs is false, 

msgAppWinDelete does not delete the document. 



msgAppWinSetUUID 

Specifies the UUID of the document to which an application window is linked. 

Takes P_UUID, returns STATUS. 

♦define msgAppWinSetUUID MakeMsg(clsAppWin, 12) 



msgAppWinCreatelcon 

Creates an application windows icon. 
Takes P_UUID, returns STATUS. 
♦define msgAppWinCreatelcon 



MakeMsg(clsAppWin, 13) 



msgAppWinDestroylcon 

Destroys an application window s icon. 
Takes P_UUID, returns STATUS. 
#define msgAppWinDestroylcon 



MakeMsg(clsAppWin, 14) 



msgAppWinStyleChanged 

Notification that an application window style changed. 

Takes OBJECT, returns STATUS. 

♦define msgAppWinStyleChanged MakeMsg(clsAppWin, 15) 

Comments Application windows send this message to their observers whenever they receive msgAppWinSetStyle. 

Note that application icon option cards will send msgAppWinSetStyle to application windows 
whenever they cause the application window's icon style to change. 



msgAppWinEditName 

Pops up an edit pad to allow the user to rename the document associated with an application window. 

Takes nothing, returns STATUS. 

♦define msgAppWinEditName MakeMsg(clsAppWin, 16) 
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This file contains the API definition for clsCorkBoardWin. 
clsCorkBoardWin inherits from clsIconWin. 

"cbwin" stands for Cork Board Window. 

Pjr Introduction 

A cork board window is an icon window associated with a document. The cork board window puts 
embedded documents in a subdirectory of the document. This frees the document's application from 
having to manage the embedded windows and documents in the cork board window. The PenPoint 
Application Framework uses clsCorkBoardWin to implement the "cork margin" that all documents 
have by default. 

Clients should rarely (if ever) need to create cork board windows themselves since the Application 
Framework has a clean UI and API for enabling the cork margin. clsApp creates a cork board window as 
the command bar of the document's main window (assuming the main window is a frame). 



Sb& Also 



app.h for messages to enable the cork margin of an application. 



#ifndef CBWIN_INCLUDED 
#define CBWIN_INCLUDED 
#ifndef ICONWIN_INCLUDED 
♦include <iconwin.h> 
#endif 



Common #delines and fypedefs 

typedef OBJECT CORKBOARD_WIN, *P_CORKBOARD_WIN; 



Pp^ Quick Help Tags 

tdefine qhCorkBoardWin 

Messages 



MakeTag (clsCorkBoardWin, 1) 



msgNew 

Creates a cork board window. 

Takes P_CORKBOARD_WIN_NEW, returns STATUS. Category: class message. 

Arguments typedef struct C0RKB0ARD_WIN_NEW_ONLY { 

U32 reservedl[4] ; 

U16 reserved2:16; 

} CORKBOARD_WIN_NEW_ONLY, *P_CORKBOARD_WIN_NEW_ONLY; 

#define corkboardWinNewFields \ 
iconWinNewFields \ 

CORKBOARD WIN NEW ONLY corkboardWin; 
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typedef struct CORKBOARD_WIN_NEW { 

corkboardWinNewFields 
} CORKBOARD WIN NEW, *P CORKBOARD WIN NEW; 



kraymenfs 



msgNewDefaults 

Initializes the CORKBOARD_WIN_NEW structure to default values. 

Takes P_CORKBOARD_WIN_NEW, returns STATUS. Category: class message. 

typedef struct CORKBOARD_WIN_NEW { 

corkboardWinNewFields 
} CORKBOARD WIN NEW, *P CORKBOARD WIN NEW; 



Zeroes out pArgs->corkboardWin and sets: 

pArgs->win . flags . style 
pArgs->win . flags . style 
pArgs->embeddedWin . style . quickMove 
pArgs->border . style . topMargin 
pArgs->border.style.bottomMargin 
pArgs->border . style . lef tMargin 
pArgs->border . style . rightMargin 
pArgs->iconWin . style . iconType 
pArgs->iconWin. style. propagatelconType 
pArgs->iconWin . style . allowOpenlnPlace 
pArgs->iconWin . style . const rainedLayout 



|= wsShrinkWrapWidth; 

| = wsShrinkWrapHeight ; 

= false; 

= bsMarginSmall; 

= bsMarginSmall; 

= bsMarginSmall; 

= bsMarginSmall; 

= awSmallPictAndTitle; 

= true; 

= false; 

= true; 



Messages from other classes 

msgEmbeddedWinGetDest 

Passes back the destination for embedded win move or copy. 

Takes P_EMBEDDED_WIN_GET_DEST, returns STATUS. 

merits clsCorkBoardWin responds by forcing the embedded document to be put in the embedding document's 

cork board subdirectory (appCorkboardDirName), creating this directory if it does not exist. 

ftis© app.h definition of appCorkboardDirName string. 
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CLSPRN.H 



This file contains the app-level API for clsPrn. 

clsPrn inherits from clsOBXService. 

Very few developers would or should deal with instances of clsPrn. Its clients would be those writing 
print-wrapper applications or printer drivers. Both kinds of clients would need far more information 
than what could be described in a header file. 

WARNING: the clsPrn API is likely to change in the future. 

Much more functionality is in clsPrn but things not documented here are GO-internal. 

#ifndef CLSPRN_INCLUDED 

tdefine CLSPRN_INCLUDED 

#ifndef OSHEAP_INCLUDED 

♦include <osheap.h> 

tendif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef OBXSVC_INCLUDED 

♦include <obxsvc.h> 

#endif 

#ifndef GEO_INCLUDED 

tinclude <geo.h> 

tendif 

tpragma pack(l) 



Common #defines and typedefs 



Popular paper types 



tdefine prnPaperLetter 





tdefine prnPaperLegal 


1 


tdefine prnPaperExec 


2 


tdefine prnPaperA4 


3 


tdefine prnPaperComlO 


4 


tdefine prnPaperMonarc 


5 


tdefine prnPaperC5 


6 


tdefine prnPaperDL 


7 


tdefine prnPaperB5 


8 


tdefine prnPaperLetterSmall 9 


tdefine prnPaperA4Small 


10 


tdefine prnPaperTypeMax 


10 


tdefine prnPaperUserDefined Oxffff 



// all printers 

// Pel, Postscript 

// Pel 

// Pel, Postscript 

// Pel 

// Pel 

// Pel 

// Pel 

// Postscript 

// Postscript 

// Postscript 
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Paper metrics 



typedef struct PAPER_CONFIG { // Paper configuration 

U16 type; // out: one of paper — above 

U16 width, height; // out: paper dimensions in mm 
U16 landscape; // out: 
U16 nCopies; // out: # of copies to print 

} PAPER CONFIG, *P PAPER CONFIG; 



Common header for all printer objects in its FS node 



typedef struct PRN_FS_HDR { 

U16 majorVersion, 
minorVersion; 

PAPER_CONFIG paper; 

U32 portMetricsFPos; 

U16 portMetricsSz; 
} PRN FS HDR, *P PRN FS HDR; 



// versioning 



Error Messages 



tdefine stsPrnStreamError 
tdefine stsPrnNoStream 
#define stsPrnUserAbort 
tdefine stsPrnFntError 



MakeStatus (clsPrn, 1) 
MakeStatus (clsPrn, 2) 
MakeStatus (clsPrn, 3) 
MakeStatus (clsPrn, 4) 



Dialog Messages 

tdefine tagPrnManualFeedDialog MakeDialogTag (clsPrn, 0) 



PJr Quick Help Id's 



tdefine tagQhPrnOptions 
tdefine tagQhPrnModel 
tdefine tagQhPrnPort 
// Epson driver specific 
tdefine tagQhEpModelSheet 
tdefine tagQhEpModelList 
tdefine tagQhEpPaperFeed 

// Pel driver specific 
tdefine tagQhPclModelSheet 
tdefine tagQhPclModelList 
tdefine tagQhPclPaperFeed 
tdefine tagQhPclBinding 



MakeTag (clsPrn, 12) 
MakeTag (clsPrn, 13) 
MakeTag (clsPrn, 14) 

MakeTag (clsEpson, 10) 
MakeTag (clsEpson, 11) 
MakeTag (clsEpson, 15) 



MakeTag (clsPcl, 10) 

MakeTag (clsPcl, 11) 

MakeTag (clsPcl, 15) 

MakeTag (clsPcl, 16) 



Argymerrt 



msgNew 

Creates a new printer object under the auspices of clsService. 
Takes P_PRN_NEW, returns STATUS. Category: class message. 



typedef struct PRN NEW ONLY { 




U16 model; 


// in: 


U16 fsNodelsNew; 


// out 


U16 filedDataSz; 


// in: 


P PRN FS HDR pFileData; 


// in: 



} PRN_NEW_ONLY, *P_PRN_NEW_ONLY; 

tdefine prnNewFields \ 
obxServiceNewFields \ 
PRN_NEW_ONLY prn; 

typedef struct PRN_NEW { 

prnNewFields 
} PRN NEW, *P PRN NEW; 



model of printer (subclass defined) 
first instantiation of object 
t of bytes to read/write from/to fs node 
pointer to read/write filed data 
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Device and Page Controls | 

Ul 

msgPrnGetPaperConfig £ 

Get the currently selected paper type, metrics and orientation. a. 

Takes P_PAPER_CONFIG, returns STATUS. Category: class message. 

#define msgPrnGetPaperConfig MakeMsg (clsPrn, 2) 

Message typedef struct PAPER_CONFIG { // Paper configuration 

Arguments U16 type; // out: one of paper — above 

U16 width, height; // out: paper dimensions in mm 

U16 landscape; // out: 

U16 nCopies; // out: # of copies to print 

} PAPER_CONFIG, *P_PAPER_CONFIG; 

msgPrnSetPaperConfig 

Set the currently selected paper type, metrics and orientation. 

Takes P_PAPER_CONFIG, returns STATUS. Category: class message. 

#define msgPrnSetPaperConfig MakeMsg (clsPrn, 3) 

Message typedef struct PAPER_CONFIG { // Paper configuration 

Arguments U16 type; // out: one of paper — above 

U16 width, height; // out: paper dimensions in mm 

U16 landscape; // out: 

U16 nCopies; // out: # of copies to print 

} PAPER_CONFIG, *P_PAPER_CONFIG; 

msgPrnGetMetrics 

Query a printer's device metrics. 

Takes P_PRN_METRICS, returns STATUS. Category: descendant responsibility. 

#define msgPrnGetMetrics MakeMsg (clsPrn, 12) 

Aigymeofs typedef struct PRN_METRICS { 

U8 prnType; // out: printer type (prnType ) 

U8 cap; // out: capability bits 

// minimum scan line count for a band buffer (if one is needed) . 

// for dot matrix printers, this should be the pin size (8 or 24) 

U16 minBandSz; 

U32 devPPMX, // out: pixel densities: 

devPPMY; // out: unit is pixels/meter 

U16 nPlanes; // out: Number of planes of the device 

// Number of colors of the device (note: this number does not 
// necessarily equal (1 « devPlanes) because of halftoning 
U16 nColors; // out: 

// currently selected paper metrics in pixels 
U16 width, height; // out: printable area size 

U16 left, right, top, bottom;// out: unprintable margins 
} PRN_METRICS, *P_PRN_METRICS; 

// PRN_METRICS. prnType 

♦define prnTypeBm // dot matrix printers 

♦define prnTypePcl 1 // HP laserjets 

#define prnTypePscript 2 // Postscript 

// PRN_METRICS . cap 

♦define prnDLBitmap 0x80 // can download bitmap font 

#define prnDLOutline 0x40 // can download outline font 

♦define prnAutoRotate 0x20 // can print in rotated mode 

♦define prnAutoCopies 0x10 // can print multiple copies of a page 
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♦define prnDuplexPrint 0x08 // can do double-sided printing 

tdefine prnSubbandable 0x04 // can create bandding region of a 

// portion of a page (relevant to a 

// banding printer only 

msgPrnStartDoc 

Prepare to start a new document. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

fdefine msgPrnStartDoc MakeMsg(clsPrn,13) 

msgPrnEndDoc 

End the currently printing document. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

tdefine msgPrnEndDoc MakeMsg(clsPrn, 14) 

msgPrnBeginPage 

Prepare to start a new page. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

tdefine msgPrnBeginPage MakeMsg(clsPrn,15) 

msgPrnShowPage 

Output the current page. 

Takes optional U16, returns STATUS. Category: descendant responsibility. 

tdefine msgPrnShowPage MakeMsg(clsPrn, 16) 

tdefine prnNextSide // if current side is front, print at back 

// if current side is back, print at front 
// msgPrnStartDoc always set the next side 
// to be the front side. 

tdefine prnFrontSide 1 // print on the front side 

tdefine prnBackSide 2 // print on the back side 

Comments P_ARGS is ignored if the printer can only do single-sided printing. P_ARGS is a number specifying page 

duplexing for printers that can do double-sided printing. 

Set the copy count. 

Takes U32, returns STATUS. Category: descendant responsibility, 
tdefine msgPrnSetCopyCount MakeMsg(clsPrn,17) 

lemmenis Valid only for devices with prnAutoCopies set in the metrics spec (msgPrnGetMetrics). 



msgPrnSetRotation 

Tell device to operate in or 90 degree mode. 

Takes BOOLEAN, returns STATUS. Category: descendant responsibility. 

tdefine msgPrnSetRotation MakeMsg(clsPrn,18) 

Comments Note: Change rotation only at the beginning of a new page. 
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Line Printer Mode Support 

For printers with the prnAuto Rotate capability, sending this message in the middle of page formatting q 

will cause undefined behavior of the printer. The co-ordinate system of the device will be rotated 2 

automatically. < 



For printers withOUT the prnAutoRotate capability, this message will only affect the metrics returned 
by the msgPrnGetMetrics call. The co-ordinate system of the device remains unaffected. 

msgPrnStartDoc will always put the device back into the non-rotated mode. 



msgPrnEnumModels 

Enumerate the models that this class supports. 

Takes P_PRN_ENUM_MODELS, returns STATUS. Category: class message. 

tdefine msgPrnEnumModels MakeMsg(clsPrn, 22) 

typedef struct { 

U16 model; // Out: model id (class defined) 

RES_ID iconResIdNormal; // Out: resld of model's normal icon 

RES_ID iconResIdSmall; // Out: resld of model's small icon 

CHAR name [nameBuf Length] ;// Out: name of model 

} PRN_MODEL, *P_PRN_MODEL; 

typedef struct { 

U16 max, // in = size of pModel[] array 

count; // in = # to return in array 

// if count > max then memory may be allocated 
// out = # of valid entries in array 
P_PRN_MODEL pModel; // in = ptr to array 

// out = if memory was allocated 

// client should free the memory 

U16 next; //in = to start at beginning 

// OR previous out value to pick up 
// where we left off 
} PRN ENUM MODELS, *P PRN ENUM MODELS; 



msgPrnGetModel 

Passes back the receiver's model. 

Takes P_PRN_MODEL, returns STATUS. 

#define msgPrnGetModel MakeMsg(clsPrn, 23) 

sage typedef struct { 

iments U16 model; // Out: model id (class defined) 

RES_ID iconResIdNormal; // Out: resld of model's normal icon 

RES_ID iconResIdSmall; // Out: resld of model's small icon 

CHAR name [nameBuf Length] ;// Out: name of model 
} PRN_MODEL, *P_PRN_MODEL; 

Line Printer Mode Support 

msgPrnMoveTo 

Move the printer's 'cursor' to the specified point. 

Takes P_XY32, returns STATUS. Category: descendant responsibility. 

#define msgPrnMoveTo MakeMsg(clsPrn, 19) 
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msgPrnGetLptFontMetrics 

Get the metrics/information of a given harware font. 

Takes P_PRN_TEXTOUT, returns STATUS. Category: descendant responsibility. 

#define msgPrnGetLptFontMetrics MakeMsg(clsPrn,20) 



msgPrnLptTextOut 

Output a line of text starting from where the printer was 'msgPrnMoveTo' last. 
Takes P_PRN_TEXTOUT, returns STATUS. Category: descendant responsibility. 
#define msgPrnLptTextOut MakeMsg(clsPrn,21) 

Arguments typedef struct PRN_TEXTOUT { 

U16 nChars; // in: number of characters to output 

P_CHAR pStr; // in: where the string is. Output will 

// be terminated if a NULL is encountered, 
// regardless of nChars . 

// additional font attributes subject to printer' s capabilities 

U16 fontSz; // in: big, medium or small 

U16 width, height; // out: character metrics in pixels 

// transformable attributes: 

// in: (msgPrnLptTextOut) specifies requested font attributes 
// BOOLEAN underline, bold, italic; 

U16 underline, bold, italic; 

// out: (msgPrnGetFontMetrics) tell client what the selected 

// font is capable of 
// BOOLEAN canUnderline, canBold, canltalic; 

U16 canUnderline, canBold, canltalic; 
} PRN_TEXTOUT, *P_PRN_TEXTOUT ; 

tdefine prnLPTSmall // fontSz field above 
tdefine prnLPTMedium 1 
#define prnLPTBig 2 

tpragma pack() 
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EMBEDWIN.H 



This file contains the API definition for clsEmbeddedWin. 

clsEmbeddedWin inherits from clsGWin. 

Embedded windows provide default functionality for embedding windows, move/copy, selection 
ownership and input target interaction. 



Other Important Files 



ewnew.h contains the API definition for creating embeddedWins. Of particular interest there are 
definitions for: 



embedded window style (EMBEDDED_WIN_STYLE) 

embedded window metrics (EMBEDDED_WIN_METRICS) 

new structs (EMBEDDED_WIN_NEW_ONLY, EMBEDDED_WIN_NEW) 

selection types (ewSelect...) 

move/copy modes 



Road Map 

Typical subclasses self send: 

♦ msgEmbeddedWinBeginMove 

♦ msgEmbeddedWinBeginCopy 

♦ several messages defined in xfer.h and sel.h 
Typical subclasses handle: 

♦ several messages defined in xfer.h and sel.h 

Subclasses that support traversal (see mark.h) probably handle: 

♦ msgEmbeddedWinShowChild 

Subclasses that manage child windows as part of their data (e.g. text editors) probably handle: 

♦ msgEmbeddedWinlnsertChild 

♦ msgEmbeddedWinExtractChild 

♦ msgEmbeddedWinPositionChild 

Subclasses that file information other than instance data (e.g. reference buttons) probably handle: 

♦ msgEmbeddedWinDestroy 

♦ msgEmbeddedWinGetDest 

♦ msgEmbeddedWinForwardedGetDest 
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Subclasses that implement sophisticated printing behavior probably handle: 

♦ msgEmbeddedWinGetPrintlnfo 

Embedding 

When an embeddedWin has style.embeddor true, it can embed all embeddedWins with style. embeddee 
true. It can also have embeddedWins moved or copied into it. Examples of embeddors are (1) cork 
margins, (2) bookshelves, and (3) the main window of most applications. An embeddedWin with 
style.embeddor true also responds to the "link" gesture (xgsDblCircle in xgesture.h) by creating a goto 
button in the window. 

When an embeddedWin has style.embeddee true, the embeddedWin can be embedded, moved and 
copied. Examples of embeddees are (1) icons for an application (2) appWins around an application's 
frame (see appwin.h) and (3) goto buttons (see goto.h). 

Move/Copy Behavior 

The header files sel.h and xfer.h describe PenPoint's move/copy mechanism. You need to understand 
PenPoint's general move/copy mechanism before you'll be able to understand embeddedWins specific 
use of it. 

clsEmbeddedWin defines a data transfer type, xferEmbeddedWin, and a corresponding data transfer 
protocol. These can be used to move and copy embeddedWins. 

Unlike most PenPoint data transfer protocols, the xferEmbeddedWin protocol is primarily a "push" 
protocol -- the destination sends a message to the source instructing the source to move/copy itself into 
the destination. 

If the source and destination agree to move data using xferEmbeddedWin, the following steps are taken. 
(This discussion assumes that the destination's style.quickMove is true; see section "Move 
Optimizations" for more information.) 

♦ The destination embeddedWin sends msgEmbeddedWinMove to the source embeddedWin to 
have the source move itself into the destination at pArgs->xy. 

♦ In response, the source self sends msgEmbeddedWinMoveCopyOK. If the resulting moveOK is 
false, the source returns stsEWSelRefusedMove. 

♦ If the destination's parent window is the same as selFs parent window, then the source 
embeddedWin "moves" itself by sending msgEmbeddedWinPositionChild to the destination. 

♦ If self and the destination are in the same process, then the source embeddedWin "moves" itself by 
sending msgEmbeddedWinExtractChild to its parent, and then sending 
msgEmbeddedWinlnsertChild to the destination. 

♦ If self and the destination are in different processes, then the source embeddedWin "moves" itself 
by (1) using msgCopy to create a copy of itself that is owned by the destination's process, and (2) 
sending msgEmbeddedWinlnsertChild to the destination. Finally the original source 
embeddedWin posts msgEmbeddedWinDestroy to itself. 

Copying data goes through the following steps: 

♦ The destination embeddedWin sends msgEmbeddedWinCopy to the source embeddedWin to 
have the source copy itself into the destination at pArgs->xy. 
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In response, the source self sends msgEmbeddedWinMoveCopyOK. If the resulting copyOK is q 

false, the source returns stsEWSelRefusedCopy. 



£ 



♦ The source embeddedWin "copies" itself by (1) using msgCopy to create a copy of itself that is 2 
owned by the destination's process, and (2) sending msgEmbeddedWinlnsertChild to the 
destination. 

Selection Interaction 

The header file sel.h describes PenPoint's selection mechanism. You need to understand PenPoint's 
general selection mechanism before you can understand embeddedWin's specific use of it. 

clsEmbeddedWin provides default selection management for itself and its subclasses. 

Some objects should take selection ownership via msgSelSetOwner and some should take ownership via 
msgSelSetOwnerPreserve. (See sel.h for complete information, but here's one example: objects in 
pop-up dialog boxes, such as option sheets, should typically take ownership via 
msgSelSetOwnerPreserve.) 

Rather than having each subclass or instance compute which way to take the selection, embeddedWin 
creators can given an embeddedWin a style.selection value which tells the embeddedWin which 
message to use to take selection ownership. 

Subclasses of clsEmbeddedWin should self send msgSelSelect to take selection ownership rather than 
sending msgSelSetOwner or msgSelSetOwnerPreserve directly to theSelectionManager. 

In response to msgSelSelect, an embeddedWin does the following: 

♦ If style.selection is ewSelect, the embeddedWin sends msgSelSetOwner to theSelectionManager 

with self as the value of pArgs. 

♦ If style.selection is ewSelectPreserve, the embeddedWin sends msgSelSetOwnerPreserve to 
theSelectionManager with self as the value of pArgs. 

♦ If style.selection is ewSelectUknown (the default), the embeddedWin searches up the window 
hierarchy looking for the first window that (1) is an embeddedWin and (2) has a style.selection 
other than ewSelectUnknown. The value of that window's style.selection is used. If no ancestor sets 
this bit, or no ancestor is an embeddedWin, the embeddedWin takes the selection via 
msgSelSetOwner. 

In addition to selection ownership message, an embeddedWin provides default responses to several 
other messages defined in sel.h. Details of each response are described with the specific messages later in 
this file. 

Input Target Interaction 

One of PenPoint's UI guidelines is that, in most cases, the selection owner should also be the input 
target. The input target receives keyboard events from the input system. (See sel.h and input.h for more 
information.) 

While PenPoint as a whole does not enforce a link between selection ownership and the input target, 
clsEmbeddedWin does. As part of its response to msgSelSelect and msgSelPromote, an embeddedWin 
makes itself the input target. 



160 PENPOINT API REFERENCE 

Part 2 / PenPoint Application Framework 

Enabling Move/Copy of the Entire Window 

If you want an entire embeddedWin to be moveable or copyable as a window, then you should set 
style.moveable and style. copyable to true. Also, you should turn on the inputHoldTimeout flag of the 
window s input flags. 

pArgs->win. flags. input |= inputHoldTimeout; 

Move Optimizations 

By default, an embeddedWin s style.quickMove is true, and the section "Move/Copy Behavior" 
correctly describes what happens during a move. But a client or subclass can set style.quickMove false, 
and thereby defeat the "same parent" and "same process" optimizations. 

tifndef EMBEDWINJENCLUDED 
#define EMBEDWIN_INCLUDED 

#if ndef EMBEDWIN_NEW_INCLUDED 

# include <ewnew.h> 

#endif 

tifndef FS_INCLUDED 
tinclude <fs.h> 
#endif 

tifndef PRINT_INCLUDED 
#include <print.h> 
#endif 



Common #defines and typedefs 

typedef OBJECT EMBEDDED WIN, *P EMBEDDED WIN; 



Status Codes 



#define stsEWNoSelection 
tdefine stsEWSelRefusedMove 
♦define stsEWSelRefusedCopy 
tdefine stsEWSelRefusedLink 
tdefine stsEWUnrecognizedFormat 
tdefine stsEWMoveToInvalidLocation 
tdefine stsEWCopyToInvalidLocation 
tdefine stsEWNotEmbeddee 
tdefine stsEWRefusedDelete 



MakeStatus (clsEmbeddedWin, 
MakeStatus (clsEmbeddedWin, 

MakeStatus (clsEmbeddedWin, 3) 

MakeStatus (clsEmbeddedWin, 4) 

MakeStatus (clsEmbeddedWin, 5) 

MakeStatus (clsEmbeddedWin, 6) 

MakeStatus (clsEmbeddedWin, 7) 

MakeStatus (clsEmbeddedWin, 8) 

MakeStatus (clsEmbeddedWin, 9) 



1) 
2) 



xferEmbeddedWin is the data transfer type clsEmbeddedWin uses to move or copy embeddedWins. 

tdefine xferEmbeddedWin MakeTag (clsEmbeddedWin, 1) 



Messages 

msgEmbeddedWinGetMetrics 



Comment 



Passes back an embeddedWin 's metrics. 

Takes P_EMBEDDED_WIN_METRICS, returns STATUS. 

tdefine msgEmbeddedWinGetMetrics MakeMsg (clsEmbeddedWin, 1) 

pArgs->uuid is set if and only if style. embeddee is true. 

See ewnew.h for the definition of P EMBEDDED WIN METRICS. 
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Move/Copy Protocol Messages 



msgEmbeddedWinGetStyle § 

ui 

Passes back an embeddedWin s style. 5 

Takes P_EMBEDDED_WIN_STYLE, returns STATUS. £ 

Q. 

#define msgEmbeddedWinGetStyle MakeMsg(clsEmbeddedWin, 2) 

Comments See ewnew.h for the definition of P_EMBEDDED_WIN_STYLE. 

msgEmbeddedWinSetStyle 

Specifies an embeddedWin's style. 

Takes P_EMBEDDED_WIN_STYLE, returns STATUS. 

♦define msgEmbeddedWinSetStyle MakeMsg(clsEmbeddedWin, 3) 

Comments If pArgs->embeddee is true and the embeddedWin's uuid is nil, a uuid is created for the window. 

Clients must not alter the value of style. moveCopyMode. 

See ewnew.h for the definition of P EMBEDDED WIN STYLE. 



Move/Copy Protocol Messages 



msgEmbeddedWinBeginMove 

Places an embeddedWin in move mode. 

Takes P_EMBEDDED_WIN_BEGIN_MOVE_COPY, returns STATUS. 

♦define msgEmbeddedWinBeginMove MakeMsg(clsEmbeddedWin, 4) 

Arguments typedef struct EMBEDDED_WIN_BEGIN_MOVE_COPY { 

XY32 xy; // x,y in source to begin move/copy. 

RECT32 bounds; // Bounding box of area to move/copy. 

U32 reserved[4] ; // Reserved. 

} EMBEDDED_WIN_BEGIN_MOVE_COPY, *P_EMBEDDED_WIN_BEGIN_MOVE_COPY; 

Comments An embeddedWin self sends this message to get itself into move mode. This message is usually self sent 

by an embeddedWin as part of the response to msgSelBeginMove if style, moveable is set. 

clsEmbeddedWin responds by creating a move icon (an instance of clsMoveCopylcon). If 
pArgs->bounds is a visible rectangle, the move icon is created with an image of what's displayed in the 
pArgs->bounds rectangle in the embeddedWin. Otherwise a default move icon is displayed centered at 
pArgs->xy. The client of the icon is self. Also style.moveCopyMode becomes ewMoveMode. 

Return Vcilue stsRequestDenied The window is already in either ewMoveMode or ewCopyMode 

See Also msgSelBeginMove 

msgEmbeddedWinBeginCopy 

Places an embeddedWin in copy mode. 

Takes P_EMBEDDED_WIN_BEGIN_MOVE_COPY, returns STATUS. 

♦define msgEmbeddedWinBeginCopy MakeMsg (clsEmbeddedWin, 5) 

message typedef struct EMBEDDED_WIN_BEGIN_MOVE_COPY { 

Arguments XY32 xy; // x,y in source to begin move/copy. 

RECT32 bounds; // Bounding box of area to move/copy. 

U32 reserved[4]; // Reserved. 

} EMBEDDED WIN BEGIN MOVE COPY, *P EMBEDDED WIN BEGIN MOVE COPY; 
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*® foments 



An embeddedWin self sends this message to get itself into copy mode. This message is usually self sent 
by an embeddedWin as part of the response to msgSelBeginCopy if style.copyable is set. 

clsEmbeddedWin responds by creating a copy icon (an instance of clsMoveCopylcon). If 
pArgs->bounds is a visible rectangle, the copy icon is created with an image of what s displayed in the 
pArgs->bounds rectangle in the embeddedWin. Otherwise a default copy icon is displayed centered at 
pArgs->xy. The client of the icon is self. Also style.moveCopyMode becomes ewCopyMode. 

teturn Value stsRequestDenied The window is already in either ewMoveMode or ewCopyMode. 

fee Also msgSelBeginCopy 



msgEmbeddedWinMove 

Moves an embeddedWin to the destination. 

Takes P_EMBEDDED_WIN_MOVE_COPY, returns STATUS. 

tdefine msgEmbeddedWinMove MakeMsg (clsEmbeddedWin, 6) 

Arguments typedef struct. EMBEDDED_WIN_MOVE_COPY { 

XY32 xy; // x,y location in dest. 

OBJECT dest; // Destination object. 

TAG format; // Data transfer format. Must be 

// xferEmbeddedWin . 
OBJECT uid; // out: moved/ copied object. 

U32 reserved[2]; // Reserved. 

} EMBEDDED_WIN_MOVE_COPY, *P_EMBEDDED_WIN_MOVE_COPY; 

Comments A destination embeddedWin sends this message to a source embeddedWin to have the source 

embeddedWin move itself to the destination. 

See the section "Move/Copy Behavior" for more information. 

tetorn Valoe stsEWSelRefusedMove The send of msgEmbeddedWinMoveCopyOK returned FALSE for moveOK. 

stsEWMoveToInvalidLocation window could not be moved to pArgs->dest. 

msgEmbeddedWinProvidelcon 

Asks an embeddedWin to provide the move/copy icon. 

Takes P_EMBEDDED_WIN_PROVIDE_ICON, returns STATUS. 

tdefine msgEmbeddedWinProvidelcon MakeMsg (clsEmbeddedWin, 23) 

Arguments typedef struct EMBEDDED_WIN_PROVIDE_ICON { 

MESSAGE msg; // msgEmbeddedWinMove or msgEmbeddedWinCopy . 

XY32 xy; // x,y in source to begin move/copy. 

RECT32 bounds; // Bounding box of area to move/copy. 

OBJECT icon; // out: the icon. 

U32 reserved [4]; // Reserved. 

} EMBEDDED_WIN_PROVIDE_ICON, *P_EMBEDDED_WIN_PROVIDE_ICON; 

Comments An embeddedWin 's default response is as follows: 

♦ if pArgs->bounds.size.w and pArgs->bounds.size.h are both greater than zero, then a marquee style 
icon is created using a "snapshot" of the screen image contained in pArgs->bounds. 

♦ Otherwise, a default move or copy icon is created. 
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msgEmbeddedWinCopy 

Copies an embeddedWin to the destination. 

Takes P_EMBEDDED_WIN_MOVE_COPY, returns STATUS. 

tdefine msgEmbeddedWinCopy MakeMsg(clsEmbeddedWin, 7) 

Message typedef struct EMBEDDED_WIN_MOVE_COPY { 

Arguments XY32 xy; // x,y location in dest. 

OBJECT dest; // Destination object. 

TAG format; // Data transfer format. Must be 

// xf erEmbeddedWin . 
OBJECT uid; // out: moved/copied object. 

U32 reserved[2]; // Reserved. 

} EMBEDDED_WIN_MOVE_COPY, *P_EMBEDDED_WIN_MOVE_COPY; 

Comments A destination embeddedWin sends this message to a source embeddedWin to have the source 

embeddedWin copy itself to the destination. 

See the section "Move/Copy Behavior" for more information. 

Return Volue stsEWSelRefusedCopy The send of msgEmbeddedWinMoveCopyOK returned FALSE for copyOK. 

stsEWCopyToInvalidLocation window could not be copied to pArgs->dest. 



rgumerts 



leturrs Value 



See Also 



msgEmbeddedWinMoveCopyOK 

Asks whether it is OK to move or copy an embeddedWin to a destination. 

Takes P_EMBEDDED_WIN_MOVE_COPY_OK, returns STATUS. 

tdefine msgEmbeddedWinMoveCopyOK MakeMsg(clsEmbeddedWin, 8) 

typedef struct EMBEDDED_WIN_MOVE_COPY_OK { 

BOOLEAN moveOK; // out: true if ok to move. 

BOOLEAN copyOK; // out: true if ok to copy. 

EMBEDDED_WIN_MOVE_COPY target; // move/copy struct. 
} EMBEDDED_WIN_MOVE_COPY_OK, *P_EMBEDDED_WIN_MOVE_COPY_OK; 

A source embeddedWin self sends this message to check that it is OK to move or copy itself to the 
destination. The default response to this message is to fill in pArgs->moveOK with style. moveable and 
pArgs->copyOK with style.copyable. 

See the section "Move/Copy Behavior" for more information. 

stsEWUnrecognizedFormat target. format was not xferEmbeddedWin. 

stsEWNotEmbeddee embeddedWin is not an embeddee. 

msgEmbeddedWinMove 



msgEmbeddedWinGetPenOffset 

Passes back the pen offset during move or copy. 

Takes P_XY32, returns STATUS. 

tdefine msgEmbeddedWinGetPenOffset MakeMsg(clsEmbeddedWin, 9) 

;©mme«fs This message allows the destination of a move or copy to determine the actual pen position relative to 

the lower-left hand corner of the move/copy icon. 

When the user lifts the pen, msgSelBeginMove passes the x,y position of the icon, not the pen. 



XY32 


xy; 


FS LOCATOR 


locator; 


U16 


sequence; 


char 


path [fsPathBuf Length] ; 


OBJECT 


source; 


U32 


reserved [3] ; 
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msgEmbeddedWinGetDest 

Get the destination for embeddedWin move or copy. 
Takes P_EMBEDDED_WIN_GET_DEST, returns STATUS. 

tdefine msgEmbeddedWinGetDest MakeMsg(clsEmbeddedWin, 10) 

#define ewPropCopyDest MakeTag(clsEmbeddedWin, 1) // Private. 

Arguments typedef struct EMBEDDED_WIN_GET_DEST { 

// x,y location in self. 

// out: Destination parent app. 

// out: Sequence in parent. 

// Path buffer for locator. 

// Object to be moved/copied. 

// Reserved. 
} EMBEDDED_WIN_GET_DEST, *P_EMBEDDED_WIN_GET_DEST; 

Some source embeddedWins move or copy more than themselves in response to 
msgEmbeddedWinMove or msgEmbeddedWinCopy. Some also transfer filed information. (For 
instance, reference buttons have to move filed information about the destination of the button.) The 
source sends msgEmbeddedWinGetDest to the destination to get the file system location that the 
destination wants the source to use for this filed information. 

An embeddedWin's default response is to (1) set pArgs->locator to OSThisAppO's locator, (2) set 
pArgs->sequence to 1, and (3) set pArgs->path to the empty string. Then if style.embedForward is true, 
msgEmbeddedWinForwardedGetDest is sent to selfs parent window. 

Corkboard Windows (clsCorkBoardWin; see cbwin.h) are an example of a class that that has a 
non-default response to this message. When an embeddedWin is copied to a cork margin, it may 
represent a document, and the source is likely to copy not only the window but also the document files 
to the destination. The cork margin cannot allow the source to copy these files into the directory of the 
cork margin's containing application since then the files would look like they're in the parent application 
~ the wrong place! So in response to msgEmbeddedWinGetDest, a corkboard window appends an 
extra directory level to is ancestor's response to msgEmbeddedWinGetDest. 

msgEmbeddedWinForwardedGetDest 

Get the destination for embeddedWin move or copy. 

Takes P_EMBEDDED_WIN_GET_DEST, returns STATUS. 

#define msgEmbeddedWinForwardedGetDest MakeMsg(clsEmbeddedWin, 22) 

typedef struct EMBEDDED_WIN_GET_DEST { 

XY32 xy; // x,y location in self. 

FS_LOCATOR locator; // out: Destination parent app. 

U16 sequence; // out: Sequence in parent. 

char path [fsPathBuf Length] ; // Path buffer for locator. 

OBJECT source; // Object to be moved/ copied. 

U32 reserved[3]; // Reserved. 

} EMBEDDED_WIN_GET_DEST, *P_EMBEDDED_WIN_GET_DEST; 

If a child embeddedWin's style.embedForward is true, then the child sends 

msgEmbeddedWinForwardedGetDest to the parent to allow the parent to override all or part of the 
child's response to msgEmbeddedWinGetDest. 

An embeddedWin's default response to this message is identical to the default response to 
msgEmbeddedWinGetDest. 
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Arguments 



Comments 



msgEmbeddedWinlnsertChild 



Asks an embeddedWin to insert a child window. 

Takes P_EMBEDDED_WIN_INSERT_CHILD, returns STATUS. 

#define msgEmbeddedWinlnsertChild MakeMsg(clsEmbeddedWin, 11) 

typedef struct EMBEDDED_WIN_INSERT_CHILD { 

XY32 xy; // x,y location in destination. 

OBJECT win; // Window to insert/extract/position. 

OBJECT source; // Requestor. 

U32 reserved[4]; // Reserved. 

} EMBEDDED_WIN_INSERT_CHILD, *P_EMBEDDED_WIN_INSERT_CHILD, 
EMBEDDED_WIN_EXTRACT_CHILD , *P_EMBEDDED_WIN_EXTRACT_CHILD , 
EMBEDDED_WIN_POSITION_CHILD, *P_EMBEDDED_WIN_POSITION_CHILD; 

clsEmbeddedWin's default response is as follows; this is illustrated in the sample code below. 

send msgEmbeddedWinGetPenOffset to pArgs->source 

offset pArgs->xy by the value passed back by msgEmbeddedWinGetPenOffset 

send msgWinlnsert to pArgs->win with self as the parent. 

XY32 xy; 

WIN_METRICS wm; 
Ob jSendUpdateRet (msgEmbeddedWinGetPenOffset, pArgs->source, fcxy, 

SizeOf (xy) ) ; 
Ob jSendUpdateRet (msgWinGetMetrics, pArgs->win, &wm, SizeOf (wm), s); 
wm. bounds. origin. x = pArgs->xy.x - xy.x; 
wm. bounds. origin. y = pArgs->xy.y - xy.y; 
ObjSendRet (msgWinDelta, pArgs->win, &wm, SizeOf (wm), s) ; 
wm. options = wsPosTop; 
wm. parent = self; 
ObjSendRet (msgWinlnsert, pArgs->win, &wm, SizeOf (wm), s) ; 

This message may be sent during a move/copy operation; see the section "Move/Copy Behavior" for 
more information. 



msgEmbeddedWinExtractChild 

Asks an embeddedWin to extract a child window. 

Takes P_EMBEDDED_WIN_EXTRACT_CHILD, returns STATUS. 

♦define msgEmbeddedWinExtractChild MakeMsg (clsEmbeddedWin, 12) 

Comments clsEmbeddedWin's default response is to ObjectSend msgWinExtract to pArgs->win. 

This message may be sent during a move/copy operation; see the section "Move/Copy Behavior" for 
more information. 



Comments 



msgEmbeddedWinPositionChild 



Asks an embeddedWin to reposition a child window. 

Takes P_EMBEDDED_WIN_POSITION_CHILD, returns STATUS. 

♦define msgEmbeddedWinPositionChild MakeMsg (clsEmbeddedWin, 13) 

clsEmbeddedWin's default response is as follows; this is illustrated in the sample code below. 

♦ send msgEmbeddedWinGetPenOffset to pArgs->source 

♦ offset pArgs->xy by the value passed back by msgEmbeddedWinGetPenOffset 

♦ self send msgWinDelta. 
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XY32 xy; 

WIN_METRICS wm; 
ObjSendUpdateRet (msgEmbeddedWinGetPenOffset, pArgs->source, &xy, 

SizeOf(xy), s) ; 
ObjSendUpdateRet (msgWinGetMetrics, pArgs->win, &wm, SizeOf(wm), s); 
wm. bounds. origin. x = pArgs->xy.x - xy.x; 
wm. bounds. origin. y = pArgs->xy.y - xy.y; 
Ob jSendRet (msgWinDelta, pArgs->win, &wm, SizeOf(wm), s) ; 

This message may be sent during a move/copy operation; see the section "Move/Copy Behavior" for 
more information. 



Linking Related Messages 



msgEmbeddedWinShowChild 

Display a given area of an embeddedWin to the user 

Takes P_EMBEDDED_WIN_SHOW_CHILD, returns STATUS. 

♦define msgEmbeddedWinShowChild MakeMsg(clsEmbeddedWin, 14) 

typedef struct EMBEDDED_WIN_SHOW_CHILD { 

WIN child; // the child directly below 

UUID childUUID; //its UUID 

RECT32 area; // area to show 

WIN areaWin; // window that the area is relative to 

} EMBEDDED_WIN_SHOW_CHILD, * P_EMBEDDED_WIN_SHOW_CHILD; 

Clients send this message to ask an embeddedWin to show the rectangle pArgs->area to the user, 
scrolling if necessary. 

Note that pArgs->area is relative to pArgs->areaWin. Therefore handling this message may involve 
transforming pArgs->area to be relative to self. This can be accomplished as follows: 

WIN_METRICS wm; 

wm. bounds = pArgs->area; 

wm. parent = self; 

ObjCallJmp(msgWinTransformBounds, pArgs->areaWin, &wm, s, Error); 

In many cases, subclasses need do nothing; clsScrollWin s response to this message takes care of it all. 

However, if a subclass does its own scrolling, manages embeddees (for example, by not having them 
inserted when off-screen) or uses something other than window coordinates to scroll a scroll window, 
then it needs to respond to this message in the following manner: 

♦ ensure that child is inserted and delta'd to the correct place (possibly scrolling it into view if needed) 

♦ transform the rect to the child (remember: it may be in some nested window) 

♦ scroll as needed to get that rect into view. 

♦ call ancestor. 

clsEmbeddedWin's default response is to set pArgs->child to self, set pArgs->childUUID to selfs UUID 
and ObjectSend the message to its parent. 
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Messages Defined in clsmgr.h 



Other Messages | 

ui 

^ms^ibeddedWinSetUUID 

< 



•omments 



Specifies an embeddedWin's uuid. o. 



Takes PJJUID, returns STATUS. 

♦define msgEmbeddedWinSetUUID MakeMsg(clsEmbeddedWin, 19) 

Gives an embeddedWin a UUID, if style. embeddee is true. 



msgEmbeddedWinDestroy 

Permanently destroys an embeddedWin. 

Takes OBJJCEY, returns STATUS. 

♦define msgEmbeddedWinDestroy MakeMsg(clsEmbeddedWin, 20) 

Comments This message is sent to an embeddedWin in response to msgSelDelete, or as the last step of 

msgEmbeddedWinMove. This message is different from msgDestroy in that this message is sent when 
the embeddedWin is being permanently destroyed and will never be restored. (msgDestroy is sent when 
the embeddedWin is being destroyed but may be restored later.) 

Any subclasses that file data to maintain information as part of their embedding behavior should free 
that data in response to this message. They should not free that data in response to msgDestroy. 

clsEmbeddedWin's default response is as follows: 

♦ if style, deleteable is false, return stsEWRefusedDelete. 

♦ Send msgEmbeddedWinDestroy to any child embeddedWins that are in the same task. 

♦ Self send msgDestroy. 

msgEmbeddedWinGetPrintlnfo 

Passes back an embeddedWin's print information. 

Takes P_EMBEDDEE_PRINT_INFO, returns STATUS. 

♦define msgEmbeddedWinGetPrintlnfo MakeMsg(clsEmbeddedWin, 21) 

Comments This message gives subclasses an opportunity to support more advanced printing of embeddedWins. 

clsEmbeddedWin's default response is to set all fields in *pArgs to 0. 



Messages Defined in clsmgr.h 



msgFree 

Defined in clsmgr.h. 

Takes OBJJCEY, returns STATUS. 



msgSave 

Defined in clsmgr.h. 

Takes P_OBJ_SAVE, returns STATUS. 

clsEmbeddedWin saves the embeddedWin's style and UUID. 
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Comments 



msgRestore 

Defined in clsmgr.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

clsEmbeddedWin restores the embeddedWin's style and UUID. 



Messages Defined in xfer.h and sel.h 



msgXferList 

Defined in xfer.h. 
Takes OBJECT, returns STATUS. 
Comments This message is sent to an object to ask it to provide the list of data transfer types it can provide. 

clsEmbeddedWin's default response is to add the transfer type xferEmbeddedWin to the end of the list. 



Comments 



Return VoSye 



msgSelMoveSelection 

Defined in sel.h. 

Takes P_XY32, returns STATUS. 

This message is sent to an object to ask it to move the selection to itself. 

See the section "Move/Copy Behavior" for more information. 

stsRequestForward embeddedWin is not an embeddor. 

stsEWSelRefusedMove destination embeddedWin refused the move. 

stsEWNoSelection No selection exists in the system. 



Comments 



Return V«Iwe 



msgSelCopySelection 

Defined in sel.h. 

Takes P_XY32, returns STATUS. 

This message is sent to an object to ask it to copy the selection to itself. 

See the section "Move/Copy Behavior" for more information. 

stsRequestForward embeddedWin is not an embeddor. 

stsEWSelRefusedCopy destination embeddedWin refused the copy. 

stsEWNoSelection No selection exists in the system. 



Comments 



msgSelRememberSelection 



Defined in sel.h. 

Takes P_XY32, returns STATUS. 

Self sent by an embeddedWin in response to the Circle-Tap gesture. 

clsEmbeddedWin's default response is to 

♦ create a reference button 

♦ insert the button by self sending msgEmbeddedWinlnsertChild. 
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Messages Defined in xfer.h and sel.h 

stsRequestForward The window is not an embeddor. g 

stsEWNoSelection No selection exists. "j 

2 



msgSelSelect a 



a. 

a 
< 

Defined in sel.h. 



Takes nothing, returns STATUS. 

See the section "Selection Interaction" for a description of an embeddedWin's response to msgSelSelect. 



msgSelPromote 

Defined in sel.h. 

Takes nothing, returns STATUS. 

clsEmbeddedWin's default response is to become the input target by calling InputSetTarget (see 
input.h) with self as the target. 

msgSelYield 

Defined in sel.h. 

Takes BOOLEAN, returns STATUS. 
Comments clsEmbeddedWin's default response is to return stsOK. 

msgSellsSelected 

Defined in sel.h. 

Takes nothing, returns BOOLEAN. 

stsOK self is the selection owner. 

other self is not the selection owner. (Note that self may be the preserved selection owner.) 

msgSelDelete 

Defined in sel.h. 

Takes U32, returns STATUS. 

See sel.h for a complete description of when this message is sent. Typically, an embeddedWin receives 
this message because the destination of the move is deleting the source. 

embeddedWin's default response is to self send msgEmbeddedWinDestroy. 

msgSelBeginMove 

Defined in sel.h. " 

Takes nothing, returns STATUS. 

See sel.h for a complete description of when this message is sent. 

clsEmbeddedWin's default response is to self send msgEmbeddedWinMove. 

stsRequestDenied the embeddedWin is already in move or copy mode. 
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sfyrn Vat 



msgSelBeginCopy 

Defined in sel.h. 

Takes nothing, returns STATUS. 

See sel.h for a complete description of when this message is sent. 

clsEmbeddedWin's default response is to self send msgEmbeddedWinCopy. 

stsRequestDenied the embeddedWin is already in move or copy mode. 



Other Messages 



msglconProvideBitmap 

Defined in icon.h. 

Takes P_ICON_PROVIDE_BITMAP, returns STATUS. 

Comments An embeddedWin receives this message from a move/copy icon (since the embeddedWin is the icon's 

client.) 

clsEmbeddedWin's default response is to forward the message to OSThisApp(). 

msgMoveCopylconDone 

Defined in mcicon.h. 

Takes OBJECT, returns STATUS. 

Comments An embeddedWin receives this message when a move/copy icon completes. (The move/copy icon 

completes when it dropped on some destination window.) 

clsEmbeddedWin's default response is to send msgSelMoveSelection or msgSelCopySelection (as 
appropriate) to the destination window. 

msgMoveCopylconCancel 

Defined in mcicon.h. 

Takes OBJECT, returns STATUS. 

Comments An embeddedWin receives this message when a move/copy icon is canceled. clsEmbeddedWin's default 

response is to take itself out of move/copy mode (by setting self's style.moveCopyMode to 
ewMoveCopyModeOff) . 



msgTrackProvideMetrics 

Defined in track.h. 

Takes P_TRACK_METRICS, returns STATUS. 

An embeddedWin receives this message from the move/copy icon's tracker. (The tracker can be 
recognized as the move/copy icon's tracker because pArgs->tag will be tagMoveCopylconTrack.) 

Subclasses can handle this message by repositioning the tracker (and therefore the move/copy icon) 
relative to the pen. This is done by modifying pArgs->initRect. Typically you do not call the ancestor in 
such cases. For instance, PenPoint's text component "jumps" the icon so that the pen is at the vertical 
center of the left edge of the icon by using code similar to the following: 
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Other Messages 

MsgHandlerArgType(SomeViewTrackProvideMetrics, P_TRACK_METRICS) q 

{ g 

if (pArgs->tag == tagMoveCopylconTrack) { S 

pArgs->initRect. origin = pArgs->origXY; 2 

pArgs->initRect. origin. y -= pArgs->initRect.size.h/2; 

return stsOK; ^ 

} else { 

return ObjectCallAncestorCtx(ctx) ; 
} 

} 



« 
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EWNEW.H 



This file contains the API definition for creating embedded windows. 

See embedwin.h for information. Essentially all of the documentation is in embedwin.h. 



#ifndef EWNEW_INCLUDED 
tdefine EWNEW_INCLUDED 
tifndef GWIN_INCLUDED 
♦include <gwin.h> 
tendif 

tifndef UUID_INCLUDED 
tinclude <uuid.h> 
tendif 

Common #defines and typedefs 

EmbeddedWin Selection Types 

Use one of these values in an embeddedWin's style.selection. 

See the section "Selection Interaction" in embedwin.h for a description of each of these values. 

tdefine ewSelectUnknown 



tdefine ewSelect 
tdefine ewSelectPreserve 



// take selection based on parent 
// embeddedWin's style.selection 

1 // take selection via msgSelSetOwner 

2 // take selection via 

// msgSelSetOwnerPreserve 



Move/Copy Modes 



These are the possible values for style.moveCopyMode. The mode is set while an embeddedWin is 
involved in a move/copy. Clients and subclasses must NOT alter the value of this field. 



tdefine ewMoveCopyModeOff 
tdefine ewMoveMode 
tdefine ewCopyMode 



Embedded Window Style 



typedef struct EMBEDDED_WIN_STYLE { 



U16 embeddor 



U16 embeddee 



U16 selection 



U16 moveable 



U16 copyable 



1; // Allow embedding. Causes response to 

// msgGWinGesture, msgEmbeddedWinMove, 

// and msgEmbeddedWinCopy . See section 

// "Embedding." 
1; // Can be embedded. Causes embeddedWin to 

// generate UUID. See section "Embedding." 
2; // Selection style. Most clients use 

// ewSelectUnknown. See section "Selection 

// Interaction." 
1; // embeddedWin is moveable. Responds 

//to msgSelBeginMove by self sending 

// msgEmbeddedWinBeginMove . 
1; // embeddedWin is copyable. Responds 

//to msgSelBeginCopy by self sending 



U16 deletable : 1 
U16 moveCopyContainer : 1 
U16 embedForward : 1 
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/ / msgEmbbeddedWinBeginCopy . 

U16 moveCopyMode : 2; // Current move/copy mode. Clients must not 

// set this field. 

// Destroy in response to msgEWDestroy? 
// Private 

// See comments with msgEmbeddedWinGetDest 
// and msgEmbeddedWinForwardedGetDest . 

U16 quickMove : 1; // Use optimizations when moving windows 

// within a common parent or within a common 
// process. True by default. See section 
// "Move Optimizations." 
// msgEmbeddedWinExtract/InsertChild. 

U16 reserved : 4; // Reserved for future use. 

U16 reserved2 : 16; // Reserved for future use. 
} EMBEDDED_WIN_STYLE, *P_EMBEDDED_WIN_STYLE ; 

Embedded Window Metrics 

Passed back from msgEmbeddedWinGetMetrics. 

typedef struct EMBEDDED_WIN_METRICS { 

UUID uuid; // Defined if style . embeddee is true. 

EMBEDDED_WIN_STYLE style; 
} EMBEDDED WIN METRICS, *P EMBEDDED WIN METRICS; 



msgNew 

Creates a new embeddedWin object. 

Takes P_EMBEDDED_WIN_NEW, returns STATUS. Category: class message. 

typedef struct EMBEDDED_WIN_NEW_ONLY { 

UUID uuid; 

EMBEDDED_WIN_STYLE style; 

U32 reserved [4]; 

} EMBEDDED_WIN_NEW_ONLY, *P_EMBEDDED_WIN_NEW_ONLY; 

♦define embeddedWinNewFields \ 
gWinNewFields \ 

EMBEDDED_WIN_NEW_ONLY embeddedWin; 

typedef struct EMBEDDED_WIN_NEW { 

embeddedWinNewFields 
} EMBEDDED_WIN_NEW, *P_EMBEDDED_WIN_NEW; 

If style.embeddor is true, objCapCreate is set in object.cap. If the passed in uuid is nil, and the object is 
an embeddee, a uuid is created. 



msgNewDefaults 

Initializes the EMBEDDED_WIN_NEW structure to default values. 

Takes P_EMBEDDED_WIN_NEW, returns STATUS. Category: class message. 

Message typedef struct EMBEDDED_WIN_NEW { 

Arguments embeddedWinNewFields 

} EMBEDDED_WIN_NEW, *P_EMBEDDED_WIN_NEW; 

Comments Zeros out pNew->embeddedWin and then executes the following: 

win. flags. style |= wsSendFile 
MakeNilUUID (pArgs->embeddedWin.uuid) ; 
pArgs->embeddedWin. style. deletable = true; 
pArgs->embeddedWin. style. quickMove = true; 
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GOTO.H 



This file contains the API definition for clsGotoButton. 

clsGotoButton inherits from clsButton. 

Provides links to other documents. 

A Goto Button is a Button associated with a Mark object. When the Goto Button is tapped, the data 
pointed to by the Mark are brought into view. Note that Goto Buttons are called Reference Buttons in 
the PenPoint User Interface. 

fifndef GOTO_INCLUDED 
tdefine GOTO_INCLUDED 

#ifndef BUTTON_INCLUDED 

♦include <button.h> 

#endif 

tifndef MARK_INCLUDED 

tinclude <mark.h> 

#endif 

typedef OBJECT GOTO_BUTTON, *P_GOTO_BUTTON; 

tdefine qhGotoButton MakeTag (clsGotoButton, 1) 



msgNew 

Creates a new Goto Button object. 

Takes P_GOTO_BUTTON_NEW, returns STATUS. Category: class message. 

typedef struct GOTO_BUTTON_NEW_ONLY { 

MARK mark; // the mark of the button, or objNull 

MARK_NEW markNew; // New structure used to create a mark 

U32 reserved[2]; // Reserved. 

} GOTO_BUTTON_NEW_ONLY, *P_GOTO_BUTTON_NEW_ONLY; 

tdefine gotoButtonNewFields \ 

buttonNewFields \ 

GOTO_BUTTON_NEW_ONLY got oButt on ; 

typedef struct GOTO_BUTTON_NEW { 

gotoButtonNewFields 
} GOTO_BUTTON_NEW, *P_GOTO_BUTTON_NEW; 

You can pass in the exact mark object that you want the Goto Button to use, or simply set up the 
markNew structure and let the Goto Button create its own mark. 



r$e$$0€|a 
Arguments 



msgNewDefaults 

Initializes a GOTO_BUTTON_NEW structure. 

Takes P_GOTO_BUTTON_NEW, returns STATUS. Category: class message. 

typedef struct GOTO_BUTTON_NEW { 

gotoButtonNewFields 
} GOTO BUTTON NEW, *P GOTO BUTTON NEW; 
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Comments clsGoto sets up the structure so that the Goto Button will create its own mark for the selection. The 

mark will be document relative because of the setting of the markForSelection and markDocRelative 
flags in the markNew structure. 

Zeroes out pArgs->gotoButton and sets 

pArgs->win . flags . input I = inputHoldTimeout ; 

pArgs->gWin.helpId = qhGotoButton; 

pArgs->erabeddedWin.style.embeddee = true; 

pArgs->embeddedWin. style. moveable = true; 

pArgs->embeddedWin. style. copyable = true; 

pArgs->embeddedWin. style. selection = ewSelect; 

pArgs->label. scale = IsScaleMedium; 

ObjectCall(msgNewDefaults, clsMark, & (pArgs->gotoButt on. markNew) ) ; 
pArgs->gotoButton. markNew. mark. flags |= markForSelection 

I markDocRelative 

I markRelaxActivate; 

msgGotoButtonGetMark 

Passes back the mark object being used by a Goto Button. 

Takes P_MARK, returns STATUS. Category: class message. 

#define msgGotoButtonGetMark MakeMsg(clsGotoButton, 1) 

msgGotoButtonGotoLink 

Jumps to the mark being used by a Goto Button. 

Takes BOOLEAN, returns STATUS. 

tdefine msgGotoButtonGotoLink MakeMsg(clsGotoButton, 3) 

If pArgs is true, turn to the document; if pArgs is false, float the document. 

msgGotoButtonDeleteLink 

Deletes a Goto Button link. 

Takes nothing, returns STATUS. 

#define msgGotoButtonDeleteLink MakeMsg(clsGotoButton, 4) 

msgGotoButtonLinkToSelection 

Links a Goto Button to the selection. 

Takes nothing, returns STATUS. 

tdefine msgGotoButtonLinkToSelection MakeMsg(clsGotoButton, 5) 

msgGotoButtonEditLabel 

Allows the user to edit a Goto Button's label. 

Takes nothing, returns STATUS. 

tdefine msgGotoButtonEditLabel MakeMsg(clsGotoButton, 7) 



Comments 
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msgGotoButtonPressed 



Sent to observers when a Goto Button has been executed. 
Takes OBJECT, returns STATUS. 



♦define msgGotoButtonPressed 
pArgs is the button that was pressed. 



MakeMsg(clsGotoButton, 6) 



msgGotoButtonResetLabel 

Causes a Goto Button to reset its label based on the thing it points to. 

Takes nothing, returns STATUS. 

#define msgGotoButtonResetLabel MakeMsg(clsGotoButton, 2) 

Comments This message is self sent at object new time, and generally should never be resent as it destroys any 

editing the user has done. 



Comments 



msgGotoButtonGetLabel 

Sent to the component containing the marked selection when the Goto Buttons label is reset. 

Takes P_GOTO_BUTTON_GET_LABEL, returns STATUS. 

♦define msgGotoButtonGetLabel MakeMsg(clsGotoButton, 8) 

typedef struct GOTO_BUTTON_GET_LABEL { 

MARK_MSG_HEADER header; 

U32 bufLen; 

P_CHAR pBuf; 

} GOTO_BUTTON_GET_LABEL, * P_GOTO_BUTTON_GET_LABEL; 

Components that support Goto Buttons should fill in the buffer (*pBuf) with the label to use. If you 
don't support this message, then clsGoto will try msgSRGetChars to get the characters pointed to by the 
mark. 



msgGotoButtonRePosition 

Sent to the component conataining the mark to request possible re-positioning for the Goto Button. 

Takes P_MARK_MESSAGE, returns STATUS. 

♦define msgGotoButtonRePosition MakeMsg(clsGotoButton, 9) 

This message is sent when a component wants the Goto Button to end up pointing at a child and not 
itself. To do this the component returns stsMarkEnterChild to this message, and then the Goto Button 
will send msgMarkGetChild to re-position the mark at the child (but not actually enter it). Most clients 
that support Goto Buttons ignore this message. 
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This file contains the API definition for clsIconWin. 

clsIconWin inherits from clsTkTable. 

Icon windows are windows that contain a number of embedded windows. 

Icon windows can manage their children icons to give them uniform appearance and layout. Icon 
windows can also force their icons to open floating, and they can deny the ability of users to set icon 
options. Examples of icon window subclasses are the Bookshelf, Accessories, and the Cork Margin. 



#ifndef ICONWIN_INCLUDED 
#define ICONWIN_INCLUDED 

#include <tktable.h> 



tifndef TKTABLE_INCLUDED 
tendif 



Common #defines and typedefs 

typedef OBJECT ICON_WIN, *P_ICON_WIN; 

Icon Window Style 

This structure defines the various icon window styles. The fields are as follows: 

♦ iconType What appearance to give the icons. The values for this field are defined in 
appwin.h, and are things like awPictAndTitle (large icon over label), awPictOnly (large icon), 
awSmallPictAndTitle (small icon to the left of a label), awSmallPictOnly (small icon), and 
awSmallPictOverTitle (small icon over label). 

♦ propagatelconType If this field is true, all icons in the icon window are forced to have the same 
iconType. If the user changes one icon's iconType, all icons in the icon window will change to 
match. 

♦ allowOpenlnPlace If this field is true, documents will be able to open inside the icon window. If 
false, documents will always open floating. 

♦ constrainedLayout If this field is true, the icon window will arrange icons into neat rows and 
columns. An icon dragged to a new location in the icon window will be "snapped" into place. If this 
field is false, icons are left where they're dropped. 

♦ showOptions If this field is true, users may make the check gesture over an icon in the icon 
window to bring up the icon option sheet. If it is false, the check gesture will be rejected. 

typedef struct ICON_WIN_STYLE { 



U16 iconType 
U16 propagatelconType 
U16 allowOpenlnPlace 
U16 constrainedLayout 
U16 showOptions 
U16 reserved 



4; // Use AppWin icon types (see appwin.h) . 

1; // True = all icons in win are same type. 

1; // False= always open floating. 

1; // True = line up icons in rows & columns. 

1; // True = allow option sheet display. 

8; // Reserved. 



} ICON WIN STYLE, *P ICON WIN STYLE; 
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Messages 



Arguments 



msgNew 

Creates a new icon window. 

Takes P_ICON_WIN_NEW, returns STATUS. Category: class message. 

typedef struct ICON_WIN_NEW_ONLY { 

ICON_WIN_STYLE style; 

U32 reserved [4]; 

} ICON_WIN_NEW_ONLY, *P_ICON_WIN_NEW_ONLY; 

♦define iconWinNewFields \ 

tkTableNewFields \ 

ICON_WIN_NEW_ONLY iconWin; 

typedef struct ICON_WIN_NEW { 

iconWinNewFields 
} ICON WIN NEW, *P ICON WIN NEW; 



Comments 



msgNewDefaults 

Initializes the ICON_WIN_NEW structure to default values. 

Takes P_ICON_WIN_NEW, returns STATUS. Category: class message. 

typedef struct ICON_WIN_NEW { 

iconWinNewFields 
} ICON WIN NEW, *P ICON WIN NEW; 



Zeroes out pArgs->iconWin and sets 

pArgs->win . flags . style 
pArgs->win . flags . style 
pArgs ->win . flags .style 
pArgs->win . flags . style 
pArgs->win . flags . style 
pArgs ->gWin . style . grabDown 
pArgs->embeddedWin . style . embeddor 
pArgs->tableLayout . style. tblXAlignment 
pArgs->tableLayout . style . tblYAlignment 
pArgs->tableLayout . style . childXAlignment 
pArgs->tableLayout . style . childYAlignment 
pArgs->tableLayout . style . growChildWidth 
pArgs->tableLayout . style . growChildHeight 
pArgs->tableLayout . style .placement 
pArgs->tableLayout . style . senseOrientation 
pArgs->tableLayout . style . reverseX 
pArgs->tableLayout . style . reverseY 
pArgs->tableLayout . numRows . constraint 
pArgs->tableLayout .numCols . constraint 
pArgs->tableLayout . rowHeight . constraint 
pArgs->tableLayout . rowHeight . gap 
pArgs->tableLayout . colWidth . constraint 
pArgs->tableLayout . colWidth . gap 
pArgs->iconWin . style . iconType 
pArgs->iconWin . style .propagatelconType 
pArgs->iconWin . style . allowOpenlnPlace 
pArgs->iconWin . style . const rainedLayout 



&= ~wsShrinkWrapWidth; 

&= ~wsShrinkWrapHeight; 

|= wsCaptureGeometry; 

|= wsClipChildren; 

|= wsHeightFromWidth; 

= false; 

= true; 

= tlAlignLeft; 

= tlAlignBottom; 

= tlAlignCenter; 

= tlAlignCenter; 

= false; 

= false; 

= tlPlaceRowMajor; 

= false; 

= false; 

= true; 

= tllnfinite; 

= tlMaxFit; 

= tlGroupMax; 

= 2; 

= tlGroupMax; 

= 3; 

= awSmallPictAndTitle; 

= false; 

= false; 

= true; 



If the environment variable "ICONWIN.SHOWOPTIONS" is set, 
pArgs->iconWin.style.showOptions is set to true, otherwise false. 



Arguments 



Comments 
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MakeMsg(clsIconWin, 1) 



msglconWinGetMetrics 

Passes back an icon window's metrics. 

Takes P_ICON_WIN_METRICS, returns STATUS. 

♦define msglconWinGetMetrics 

typedef struct ICON_WIN_METRICS { 

ICON_WIN_STYLE style; 

U32 reserved [4]; 

} ICON_WIN_METRICS, *P_ICON_WIN_METRICS; 

Since the icon window metrics structure currently contains no information other than the icon window 
style, use msglconWinGetStyle instead of this message. 



Message 
Arguments 



msglconWinGetStyle 

Passes back an icon window's style. 

Takes P_ICON_WIN_STYLE, returns STATUS. 

tdefine msglconWinGetStyle 



MakeMsg(clsIconWin, 2) 



typedef struct ICON WIN STYLE { 



U16 iconType 
U16 propagate IconType 
U16 allowOpenlnPlace 
U16 const rainedLayout 
U16 showOptions 
U16 reserved 



// Use AppWin icon types (see appwin.h) . 

// True = all icons in win are same type. 

// False= always open floating. 

// True = line up icons in rows & columns, 

// True = allow option sheet display. 

// Reserved. 



} ICON WIN STYLE, *P ICON WIN STYLE; 



Mes$cs§e 
Argyments 



msglconWinSetStyle 

Specifies an icon window's style. 

Takes P_ICON_WIN_STYLE, returns STATUS. 

tdefine msglconWinSetStyle 



MakeMsg(clsIconWin, 3) 



typedef struct ICON_WIN_STYLE { 



U16 iconType 
U16 propagate IconType 
U16 allowOpenlnPlace 
U16 const rainedLayout 
U16 showOptions 
U16 reserved 



// Use AppWin icon types (see appwin.h) . 

// True = all icons in win are same type. 

// False= always open floating. 

// True = line up icons in rows & columns. 

// True = allow option sheet display. 

// Reserved. 



} ICON WIN STYLE, *P ICON WIN STYLE; 



HaUUM" 






|3Mm! 



fwSlS& 



DAD V 



PENPOINT API 

"% / BEUBAIMf 

Jk / r m vi r %9 I W T 






M^^^SJ^tefflM J^M^^ ffiftiMB^i^ i i^^ ^ 




MARK.H 



clsMark 

clsMark inherits from clsObject. 

clsMark provides a path to interact with data in other, possibly nested, components. It is used by Goto 
Buttons, Search/Replace, and Spell. 

goto.h, sr.h 



Overview 



PenPoint allows parts of the system, such as search and replace, spell checking and reference buttons, to 
operate and refer to data in any document or nested embedded documents. This generic reference to 
data is done with clsMark. In order for clsMark to work, applications must support the client side of 
clsMark s protocol and the client side of the various system protocols (which are described elsewhere, 
specifically in sr.h and goto.h). 

What follows describes in more detail how clsMark relates to the rest of PenPoint. You may wish to skip 
ahead to the Example and/or Quick Start sections and refer back to here later. 

In PenPoint, the data that make up a document are held in one or more 'components'. Typically these 
components are descendants of clsEmbeddedWin. Alternatively, your descendant of clsApp might hold 
all the data. In either case the individual pieces of data (individual words in a text component, shapes in 
a drawing component, etc.) are only accessible via the component object. No other object knows how 
the data is actually stored and the data are not usually accessible as objects outside the component. 

There are times, however, when these individual data items need to be manipulated from outside of your 
application. Goto buttons, for example, allow a user to create a link to such a data item, and later turn 
back to it. Search & Replace, which is driven by a PenPoint supplied manager, needs to access successive 
pieces of text in both your application and documents embedded within you. 

An instance of clsMark, (from now on, simply 'a mark',) is a reference to a data item in a component. 
We call this data item the 'target' as it is this data item that a Goto button or Search is really interested 
in, not the component that contains it. The object that uses the mark is called the 'holder' of the mark. 
A mark may be persistent or temporary. In the former case, once established a mark will remain valid 
across document shut-downs and re-boots. In the latter, the mark is valid only so long as the component 
remains active. 

In order to support marks a component must create a mapping between the two U32s, or 'token', that a 
mark holds and its data items. For example, a data base might use this to hold a record number. 
Remember that the mark might persist beyond a single operation. Therefore, a text editor would NOT 
use these U32s to be a character position. This is because if a mark is created for a word, and then text is 
deleted before the word, the desired action is for the mark to still refer to the word which has now 
moved in character position. Remember: once a mark has been created for a piece of data, there is no 
way for the component to update the token it has given for it. 
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An Example 

The process of using a mark is best illustrated by the Search & Replace mechanism in PenPoint: 

Search/Replace, Spelling, etc. use the mark mechanism to traverse the contents of applications. All 
applications that allow themselves to be searched, spelled or printed support the component half of this 
protocol. Implementors of new functionality similar to Search/Replace, Spell, or Print must implement 
the driver half of the protocol. 

When the user selects Find from the Edit menu, the Search Manager responds by displaying an option 
sheet and by creating a mark which initially points to the document the user is working in. 

As the user requests find and replace operations, the Search Manager calls the mark with 
msgMarkDeliver with arguments specifying the clsSR messages it wants sent to the component. In turn, 
the mark sends those messages, along with its own messages to the component and, if requested, each 
nested component. It is these messages that a client must implement. (The clsMark messages are 
described in this file, the clsSR messages are in sr.h.) 

After the component performs the request find and/or replace, the status is passed back all the way to 
the Search Manager which lets the user know. Note that the messages to hilite and select the found text 
are also passed from the Search Manager to the component this way. 

Quick Start 

How to be a Client that Supports Marks 

1) You must decide how to refer to the data items in the component via tokens. There are several 
considerations: How will you treat marks that survive save & restore? How will the mark be affected by 
edit operations? What is the ordering of data items (even if the data items have no intrinsic ordering, 
you will still need a way to enumerate over them in some serial order)? Do you inherit markable data 
from your ancestor that you don't take care of. 

2) Support the basic messages: 

♦ msgMarkCreateToken 

♦ msgMarkDeleteToken (if necessary) 

♦ msgMarkGetDataAncestor 

3) For a component that can be traversed, support the following. These are typically very easy to 
implement, and all markable components should support them. 

♦ msgMarkPositionAtEdge 

♦ msgMarkPositionAtToken 

♦ msgMarkCompareTokens 

4) If the component has a graphical view of the data, support the following. This allow Goto Buttons to 
work (first three messages) and the Search & Replace and Spell gestures to work (last message). 

♦ msgMarkShowTarget 

♦ msgMarkSelectTarget (if it can hold the selection) 

♦ msgMarkPositionAtSelection (if it can hold the selection) 

♦ msgMarkPositionAtGesture (if it can target gestures to data) 
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Quick Start 

5) If the component has any text as data, support the following. These support the text side of both § 
Search & Replace and Spell. They are also used by reference buttons. See sr.h for a description of these 2 
messages. < 

u. 

♦ msgSRNextChars £ 

< 

♦ msgSRGetChars 

♦ msgSRPositionChars 

♦ msgSRReplaceChars (if replacement is possible) 

6) If your component manages its own embedees, support: 

♦ msgMarkPositionAtChild 

♦ msgMarkNextChild 

♦ msgMarkGetChild 

7) If you component is not a descendant of clsEmbeddedWin or clsApp then it must support the 
following messages: 

♦ msgMarkGetParent 

♦ msgMarkGetUUIDs 

How to be a Driver that Uses Marks 

1) Send msgNewDefaults and msgNew to clsMark. This creates the initial mark and sets up the 
component for the mark. 

2) Send the appropriate msgMarkPosition... message. This sets the mark at the place where you want it. 
You are free to define new kinds of positioning messages, so long the components you work with 
support them. As a back-up, you should always be prepared to deal with stsMsgNotUnderstood as a 
response from a message sent to a component. In that case, do the default action (try 
msgMarkPositionAtEdge) . 

3) If you need to manipulate the mark, send messages via msgMarkDeliver, msgMarkDeliverPos, 
and/or msgMarkDeliverNext. These will instruct the component to take the appropriate action on the 
target and the mark. Again, be prepared to deal with stsMsgNotUnderstood. Try to use standardized 
messages, such as msgSRNextChars, when your specific ones fail. Remember: an embedded document 
may not know the protocol the enclosing document does and vice versa. 

4) You can file and unfile the mark as you would with any other object. The mark will remain connected 
to the target. Note that once a mark has been filed it is now permanent; this will likely consume 
resources at the component that has the target. 

5) Send msgDestroy to the mark when you are done with it. 

tifndef MARK_INCLUDED 
#define MARK_INCLUDED 1 

#ifndef GO_INCLUDED 
tinclude <go.h> 
#endif 

tifndef UUID_INCLUDED 
#include <uuid.h> 
#endif 

tifndef GWIN_INCLUDED 
tinclude <gwin.h> 
tendif 
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Statuses 



#define 
#define 
#define 
tdefine 

tdefine 
tdefine 
♦define 
#define 



stsMarkNoUUIDs 

stsMarkRedirectMark 

stsMarkNoWin 

st sMarkNoComponent 

st sMarkComponent sDi f f er 

st sMarkTokensEqual 

stsMarkTokenAfter 

s t sMarkTokenBe fore 



tdefine stsMarkEnterChild 
tdefine stsMarkRetry 
tdefine stsMarkSkipChild 
tdefine stsMarkNot Active 



MakeStatus(clsMark, 1) 

MakeStatus(clsMark, 2) 

MakeStatus(clsMark, 3) 

MakeSt atus ( clsMark , 4 ) 

MakeWarning(clsMark, 10) 

MakeWarning ( cl sMark , 11) 

MakeWarning (clsMark, 12) 

MakeWarning ( cl sMark , 13) 

MakeWarning (clsMark, 20) 

MakeWarning (clsMark, 21) 

MakeWarning (clsMark, 22) 

MakeWarning (clsMark, 23) 



Common #def ines and Types 



typedef OBJECT MARK, * P_MARK; 

typedef struct MARKJTOKEN { 

CLASS classLevel; 

U32 index; 

U32 index2; 

} MARK_TOKEN, * P_MARK_TOKEN; 

typedef struct MARK COMPONENT { 



// which class level is the data at 
// index to the data item 
// secondary index if needed 



UUID 


appUUID; 


UUID 


compUUID; 


UID 


compUID; 



} MARK_COMPONENT, * P_MARK_COMPONENT ; 

MARK_FLAGS 

These flags are used when creating a mark. They indicate what kind of mark is to be created. 

markDocRelative makes the mark save its component reference relative to OSThisApp. This means 
that if the mark is saved, and both the document that contains the mark and the document it refers 
to are copied in a single operation, the new set will refer to within itself correctly. This is what goto 
buttons do. 

markForSelection automatically positions the mark at the selection, including finding out who the 
selection holding component is. If you set this, then you don't need to set any other fields in the 
new struct. 

markAlwaysDelete once a mark has been saved, it remembers that it can never delete the token 

because it has no idea how many copies of the file it was saved in have been made. This flag forces 
marks to always delete the token no matter what. If you manage the reference of this mark and you 
can guarantee that what ever happens to the saved mark happens to the component it refers to, then 
set this flag. 

markRelaxActivate this keeps a mark from activating the component on entering and exiting. If the 
component isn't active on entering, it will be skipped if possible or it will be referred to in its 
entirety. If the component is not active on exiting, then it will miss the delete token message. Note 
that this can cause resource leaks at the expense of keeping the UI snappy. This takes precedence 
over markAlwaysDelete. 



typedef U32 MARK_FLAGS, * P_MARK_FLAGS ; 

tdefine markDocRelative flagl 

tdefine markForSelection flag2 

tdefine markAlwaysDelete flag3 

tdefine markRelaxActivate flag4 



// if saved, document relative 
// make mark for the selection 
//if you manage the destination 
// don't always activate 



typedef U16 MARK_MSG_FLAGS , * P_MARK_MSG_FLAGS ; 



MARK.H 187 

Common #defines and Types 

at 
These flags are only valid with msgMarkDeliverPos & msgMarkDeliverNext 9 

UJ 

♦define markMsgNormal // standard message send 

tdefine markMsgTry 1 // one in a sequence of possible messages 

#define markMsgLastTry 2 // last in a sequence of messages ^ 

#define markMsgMode 3 // '&' with flags to extract flag field < 

These flags are only valid with msgMarkDeliverNext 

#define markBackward flag8 // direction of movement is reversed 

#define markEnterNone // enter no children 

tdefine markEnterAll flag9 // enter all children 

tdefine markEnterOpen flaglO // enter only open children 

#define markEnterMode (flag9|flagl0) // '&' with flags to extract Enter 

// field 

tdefine markExitUp flagll // at end, move up to parents 

// default flag settings: 

tdefine markDefaultMsgFlags 

tdefine markDefaultPosMsgFlags markMsgNormal 

tdefine markDefaultNextMsgFlags \ 

(markMsgNormal | markEnterOpen | markExitUp) 

MARK_MSG_HEADER must be the start of the argument structure for any message delivered via 
msgMarkDeliver, msgMarkDeliverPos, or msgMarkDeliverNext. It allows clsMark to insert the token 
information into the message arguments to indicate which part of the component is to be operated on. 

typedef struct MARK_MSG_HEADER { 

MARK_TOKEN token; // Supplied by mark: the token 

MESSAGE msg; // In: the message to send 

SIZEOF lenArgs; // In: length of the whole structure 

MARK_MSG_FLAGS flags; // In: flags as appropriate 
} MARK_MSG_HEADER, * P_MARK_MSG_HEADER; 

typedef struct MARK_MESSAGE { 

MARK_MSG_HEADER header; 
} MARK_MESSAGE, * P_MARK_MESSAGE; 
typedef U16 MARK_LOCATION; 

tdefine markLocWhole 
tdefine markLocBeginning 1 
tdefine markLocEnd 2 

The following location codes are only valid for msgMarkPositionAtGesture These may be or'd together 
and in with the above codes... 

tdefine markLocWholeWord flag4 // use the whole word under the gesture 
tdefine markLocUseSelection flag5 // use the selection if the gesture was 

// over it 

Important: all message handlers for messages sent via msgMarkDeliver, msgMarkDeliverPos, or 
msgMarkDeliverNext, must have the following as its first statement. Replace "clsYourClassHere" with 
the uid of your class. 

MarkHandlerForClass (clsYourClassHere) ; 

tdefine MarkHandlerForClass (els) \ 

if (WKNValue(((P_MARK_TOKEN)pArgs)->classLevel) != WKNValue(cls) ) \ 
return Ob jectCallAncestor (msg, self, pArgs, ctx) ; 
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Messages 



msgNew 

Creates a new mark, initialized to the given component (if any). 

Takes P_MARK_NEW, returns STATUS. Category: class message. 

irgomenfs typedef struct MARK_NEW_ONLY { 

MARK_FLAGS flags; 

MARK_COMPONENT component; 
U16 reserved [2]; 

} MARK_NEW_ONLY, * P_MARK_NEW_ONLY; 

tdefine markNewFields \ 

objectNewFields \ 

MARK_NEW_ONLY mark; 

typedef struct MARK_NEW { 

markNewFields 
} MARK_NEW, * P_MARK_NEW; 

The fields you might typically set are pArgs->mark.flags: or in markForSelection to refer to the 
selection object, or in markDocRelative if you ever plan on saving the mark object 
pArgs->mark.component.compUID: the object to refer to (not needed if you set markForSelection 
above) 



msgNewDefaults 

Initializes the MARK_NEW structure to default values. 

Takes P_MARK_NEW, returns STATUS. Category: class message. 

Message typedef struct MARK_NEW { 

Arguments markNewFields 

} MARK_NEW, * P_MARK_NEW; 

Comments Zeroes out pNew->mark. Specifically, this includes: 

MakeNilUUID (pArgs->mark . component . appUUID) ; 
MakeNilUUID (pArgs->mark . component . compUUID) ; 
pArgs ->mark. component .compUID = objNull; 



msgMarkDeliver 

Delivers a message to the target that does not move the token. 

Takes P_MARK_MESSAGE, returns STATUS. 

tdefine msgMarkDeliver MakeMsg(clsMark, 1) 

Message typedef struct MARK_MESSAGE { 

Arguments MARK_MSG_HEADER header; 

} MARK_MESSAGE, * P_MARK_MESSAGE; 

Comments The message in pArgs->header.msg is sent to the component after the mark fills in the token field. Note 

that the pArgs for the sent message are the same as the pArgs that are passed in to msgMarkDeliver. 
Various messages that are sent to components have extra fields tacked on to this structure. Therefore, all 
messages delivered with msgMarkDeliver MUST have a pArgs structure that starts with same fields as 
MARKJDEIXVER. Furthermore, the lenArgs field must be set to the size of the WHOLE structure. 



MARK.H 189 

Messages 



msgMarkDeliverPos § 

in 

Delivers a message to the target that moves the token but does not change the component. ^ 

as 

Takes P_MARK_MESSAGE, returns STATUS. £ 

a. 

tdefine msgMarkDeliverPos MakeMsg(clsMark, 2) 

Message typedef struct MARK_MESSAGE { 

Arguments MARK_MSG_HEADER header; 

} MARK_MESSAGE, * P_MARK_MESSAGE; 

Comments This is just like msgMarkDeliver, only it is used to deliver a message that will potentially reposition the 

mark elsewhere in the component. It is chiefly used with the msgMarkPosition... messages. 

The additional flags argument is used to determine how the holder wants to interpret the response from 
the client. Normally you use markMsgNormal, which automatically deals with certain client response 
codes that the holder doesn't need to be aware of. 

For example, if a holder wants to use msgMarkPositionAtEdge the code would be: 

MARK_POSITION_EDGE edgeArgs; 

edgeArgs.msg = msgMarkPositionAtEdge; 

edgeArgs . lenArgs = SizeOf (MARK_POSITION_EDGE) ; 

edgeArgs . flags = markMsgNormal; 

edgeArgs. location = markLocBeginning; 

Ob jCallRet (msgMarkDeliverPos, aMark, &edgeArgs) ; 

However, if the holder wishes to try a different positioning message if the first one fails, then the holder 
must use the flag setting markMsgTry on all except the last message which uses markMsgLastTry. 
Furthermore, these must be in a while loop and repeated if stsMarkRetry is ever returned. 

For example, if a holder would like to use the (hypothetical) message msgPositionAtVowel, and if that 
fails use msgPositionAtLetter, and if that fails try msgPositionAtCharacter; then it the code would be: 



POS VOWEL 


posVowel; 


POS LETTER 


posLetter; 


POS CHAR 


posChar; 


STATUS 


s; 



while (true) { 

posVowel. msg = msgPositionAtVowel; 

posVowel . lenArgs = SizeOf (POS_VOWEL) ; 

posVowel. flags = markMsgTry; 

posVowel. ... = ... // other arguments 

s = Ob jectCall (msgMarkDeliverPos, aMark, SposVowel) ; 

if (s == stsMarkRetry) continue; 

if (s != stsMsgNotUnderstood) break; // some error occurred 

posLetter. msg = msgPositionAtLetter; 

posLetter. lenArgs = SizeOf (POS_LETTER) ; 

posLetter. flags = markMsgTry; 

posLetter. ... = ... // other arguments 

s = ObjectCall (msgMarkDeliverPos, aMark, fcposLetter) ; 

if (s == stsMarkRetry) continue; 

if (s != stsMsgNotUnderstood) break; // some error occurred 

posChar.msg = msgPositionAtCharacter; 

posChar . lenArgs = SizeOf (POS_CHAR) ; 

posChar . flags = markMsgLastTry; 

posChar. ... = •. . . // other arguments 

s = ObjectCall (msgMarkDeliverPos, aMark, SposChar) ; 

if (s == stsMarkRetry) continue; 

if (s != stsMsgNotUnderstood) break; // some error occurred 

//do what you do if none were understood 
} 
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While this code is a little complicated, it allows the holder to deal with a variety of components that 
may know different messages. The while loop and stsMarkRetry are necessary for the handling of 
inherited component data and behavior. (Specifically, while the mark takes care of most of the chore of 
moving from level to level in a components class hierarchy, only the holder knows the sequence of 
messages to try at each level, so the stsMarkRetry acts as a sentinel to the holder to retry the full 
sequence again.) 



msgMarkDeliverNext 

Delivers a message to the target that moves the token and sometimes (but not always) changes the 
component. 

Takes P_MARK_MESSAGE, returns STATUS. 

tdefine msgMarkDeliverNext MakeMsg(clsMark, 3) 

typedef struct MARK_MESSAGE { 

MARK_MSG_HEADER header; 
} MARK_MESSAGE, * P_MARK_MESSAGE; 

This is the same as msgMarkDeliverPos, only it is used when the repositioning of the token may result 
moving to a new component. This may happen in messages like msgSRNextChars where the next string 
to search is in an embedded component. 

The flags field is used the same way as in msgMarkDeliverPos. The flags field also carries some 
additional flags: These indicate which direction the movement is in, and what to do about embedded 
components and what to do at the end of a component. 

All components that respond to messages sent via msgMarkDeliverNext are responsible for two things: 

-: They must check the markBackward flag to determine the direction of motion. 

-: If they encounter a child window as the next item, regardless of what the message is looking for, 
then the token needs to be set to refer to that child and stsMarkEnterChild needs to be returned. 



msgMarkSend 

Sends a message to a component with no further processing. 

Takes P_MARK_SEND, returns STATUS. 

#define msgMarkSend MakeMsg(clsMark, 9) 

typedef struct MARK_SEND { 

MESSAGE msg; // the message to send 

P_ARGS pArgs; // pointer to the arguments 

SIZEOF lenArgs; // length of those arguments 

} MARK_SEND, * P_MARK_SEND ; 

Sends a message to the component. Note that this allows you to send any arbitrary message. However, 
unlike the msgMarkDeliver messages, msgMarkSend doesn't copy the token value of the mark into the 
argument structure passed to the component. Hence, no indication of what the target is goes with the 
message. This is rarely what you want. 

The rule is: any message designed to be used with marks should use one of the msgMarkDeliver forms. 
Any message NOT designed to work with marks (and thus has no specific target) should use 
msgMarkSend. 
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msgMarkSetComponent 

Sets the mark to refer to the given component. 

Takes P_MARK_COMPONENT, returns STATUS. 

♦define msgMarkSetComponent MakeMsg(clsMark, 4) 

Message typedef struct MARK_COMPONENT { 

Arguments UUID appUUID; 

UUID compUUID; 

UID compUID; 

} MARK_COMPONENT, * P_MARK_COMPONENT ; 

Comments You set the fields of the MARK_COMPONENT one of three ways (zeroing the unused fields): 

♦ Set pArgs->compUID to refer to a specific component object 

♦ Set pArgs->appUUID to refer to an application object by UUID 

♦ Set pArgs->appUUID and pArgs->compUUID to refer to a component in an application by 
UUIDs 

This will delete the previous mark, if necessary and send a msgMarkCreateToken to the new 
component. 

To make the mark point at nothing, pass it a pointer to an all-zero structure; do NOT pass it a null 
pointer! 

msgMarkGetComponent 

Returns the UUID of the app the contains the token and the UUID and UID of the component that 
contain the token. 

Takes P_MARK_COMPONENT, returns STATUS. 

tdefine msgMarkGetComponent MakeMsg(clsMark, 5) 

message typedef Struct MARK_COMPONENT { 

Arguments UUID appUUID; 

UUID compUUID; 

UID compUID; 

} MARK_COMPONENT, * P_MARK_COMPONENT; 

Comments If the app is not open, then pArgs->compUID will be objNull. If the target is in the app object, then 

pArgs->compUUID will be zeros. 

msgMarkCompareMarks 

Determines if two marks refer to the same component, and, if so, what order their targets are in. 
Takes MARK, returns STATUS. 

tdefine msgMarkCompareMarks MakeMsg(clsMark, 6) 

leturm Volue stsMarkTokensEqual the targets of the marks are the same 

stsMarkTokenAfter the target of the receiver is after the argument 
stsMarkTokenBefore the target of the receiver is before the argument 



BOOLEAN noSelect 


1, 


noDisplay 


1, 


turnTo 


1, 


bringTo 


1, 


reserved 


12; 
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msgMarkCopyMark 

Creates a new mark, identical to this mark. 

Takes P_MARK, returns STATUS. 

tdefine msgMarkCopyMark MakeMsg(clsMark, 7) 

Because marks can't easily reverse direction across components, it's sometimes desirable to save the 
original position. Since the duplicate mark is independent of the original, it doesn't move when the 
original does. 

msgMarkGotoMark 

Causes a mark to be selected and displayed to the user. 

Takes P_MARK_GOTO, returns STATUS. 

#define msgMarkGotoMark MakeMsg(clsMark, 8) 

typedef struct MARK_GOTO { 

//inhibits the selection of the target 

//inhibits the display of the target 

//if closed, will do a turn to 

//if closed, will do a bring to 
2; 
} MARK_GOTO, * P_MARK_GOTO; 

Comments By default, the target is selected and scrolled on screen, provided the document is on screen. Optionally, 

the document can be activated and either turned to or floated on screen. 

Messages Sent to Components 

Important: message handlers for the first three messages (msgMarkCreateToken, 
msgMarkDeleteToken, and msgMarkCompareTokens) must have the following as its first statement. 
Replace "clsYourClassHere" with the uid of your class. 

MarkHandlerForClass (clsYourClassHere) ; 

msgMarkCreateToken 

Instructs a component to create a token for its data items, and start the token pointing at before all data 
items. 

Takes P_MARK_TOKEN, returns STATUS. 

#define msgMarkCreateToken MakeMsg(clsMark, 40) 

Message typedef struct MARK_TOKEN { 

Arguments CLASS classLevel; // which class level is the data at 

U32 index; // index to the data item 

U32 index2; // secondary index if needed 

} MARK_TOKEN, * P_MARK_TOKEN; 

Comments You can only forget about the token associated with a mark when a corresponding 

msgMarkDeleteToken is received, or the target data is deleted. In the later case you must be careful 
never to generate that token again as there still might be outstanding tokens for it. 
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* 

msgMarkDeleteToken § 

UJ 

Tells a component that the given token will no longer be in use. 

Takes P_MARK_TOKEN, returns STATUS. a. 

a. 

#define msgMarkDeleteToken MakeMsg(clsMark, 41) 

lessoge typedef struct MARK_TOKEN { 

arguments CLASS classLevel; // which class level is the data at 

U32 index; // index to the data item 

U32 index2; // secondary index if needed 

} MARK TOKEN, * P MARK TOKEN; 



ifum Value 



See msgMarkCreateToken. 



msgMarkCompareTokens 

Asks a component to compare the ordering of two tokens. 

Takes P_MARK_COMPARE_TOKENS, returns STATUS. 

#define msgMarkCompareTokens MakeMsg(clsMark, 42) 

typedef struct MARK_COMPARE_TOKENS { 

MARK_TOKEN f irst Token; 

MARK_TOKEN secondToken; 

} MARK_COMPARE_TOKENS, * P_MARK_COMPARE_TOKENS ; 

stsMarkTokensEqual the two tokens point to the same place 

stsMarkTokenAiter the first token comes after the second 

stsMarkTokenBefore the first token comes before the second 

msgMarkGetDataAncestor 

Asks for the next higher superclass that contains traversable data. 

Takes P_CLASS, returns STATUS. 

tdefine msgMarkGetDataAncestor MakeMsg(clsMark, 46) 

Asks a component what the next ancestor the argument inherits data from. The component s response 
should is based on what the argument is. Assuming the class of the component is clsMyThing: 

objNull respond with clsMyThing 

clsMyThing respond with the next class clsMyThing gets data from, typically clsEmbeddedWin or 
objNull (if none). 

otherwise call the ancestor 

Example 

if (*pArgs == objNull) *pArgs = clsMyThing; 

else if (*pArgs == clsMyThing) *pArgs = clsEmbeddedWin; 
else Ob jCallAncestorCtxRet (ctx) ; 

return stsOK; 

If your code doesn't inherit data then you'll do the following: 

if (*pArgs == objNull) *pArgs = clsMyThing; 
else *pArgs = objNull; 

return stsOK; 
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msgMarkGetParent 

Asks a component to set the argument to its parent (embedding) component. 

Takes P_MARK_COMPONENT, returns STATUS. 

tdefine msgMarkGetParent MakeMsg(clsMark, 43) 

typedef struct MARK_COMPONENT { 

UUID appUUID; 

UUID compUUID; 

UID compUID; 

} MARK_COMPONENT, * P_MARK_COMPONENT ; 

Either the UID or the UUIDs should be filled in, mark will take care of the rest. If the component is 
descended from clsEmbeddedWin or clsApp, it already inherits the correct response and 
implementation is necessary. 

msgMarkGetUUIDs 

Asks a component to set the argument to its own app and component UUIDs if it can. 

Takes P_MARK_COMPONENT, returns STATUS. 

tdefine msgMarkGetUUIDs MakeMsg(clsMark, 45) 

typedef struct MARK_COMPONENT { 

UUID appUUID; 

UUID compUUID; 

UID compUID; 

} MARK_COMPONENT, * P_MARK_COMPONENT ; 

If it can't it should return stsMarkNoUUIDs. If your component is a descendant of clsApp or 
clsEmbeddedWin then you inherit the correct implementation. 



msgMarkValidateComponent 

Asks a component to verify that it is okay to traverse it. 

Takes P_MARK_COMPONENT, returns STATUS. 

tdefine msgMarkValidateComponent MakeMsg(clsMark, 44) 

typedef struct MARK_COMPONENT { 

UUID appUUID; 

UUID compUUID; 

UID compUID; 

} MARK_COMPONENT, * P_MARK_COMPONENT ; 

This message is sent to objects before a mark refers to them. This gives an object a chance to point the 
mark at a different object as the component. Typically, a driver might create a mark with the selection 
holder as the component. However, the selection holder might not be the desired component for a mark 
(the selection could be a data object, but the mark component should be the app object). Mark sends 
this message to the proposed component. The proposed component then can either not implement the 
message (or return stsOK) or set the argument to another component object and return 
stsMarkRedirectMark. In the first case the proposed component becomes the used component, in the 
second the returned component becomes the new proposed component. 
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f Messages Sent to Components via 
msgMarkDeliver 

Note: As these are defined in clsMark, these messages may be sent to the mark directly without using 
msgMarkDeliver, msgMarkDeliverPos, or msgMarkDeliverNext (with mode = markMsgNormal) as < 

appropriate. As usual, the mark and token fields will be filled in by the mark, and then the message 
passed on. 

In addition special processing will be done for some of the messages which would NOT be done if the 
message was sent via standard delivery messages. This processing is noted for those messages under the 
heading: 'If sent directly to mark 

Important: all message handlers for these messages must have the following as its first statement. 
Replace "clsYourClassHere" with the uid of your class. 

MarkHandlerForClass (clsYourClassHere) ; 

msgMarkPositionAtEdge 

Asks a component to reposition the token to one end or the other of the data. 

Takes P_MARK_POSITION_EDGE, returns STATUS. 

#define msgMarkPositionAtEdge MakeMsg (clsMark, 80) 

Arguments typedef Struct MARK_POSITION_EDGE { 

MARK_MSG_HEADER header; 

MARKJLOCATION location; // either markLocBeginning or markLocEnd 

} MARK_POSITION_EDGE, * P_MARK_POSITION_EDGE; 

msgMarkPositionAtToken 

Asks a component to reposition the token to the same position as another token for the same 
component. 

Takes P_MARK_POSITION_TOKEN, returns STATUS. 

♦define msgMarkPositionAtToken MakeMsg (clsMark, 81) 

Arguments typedef struct MARK_POSITION_TOKEN { 

MARK_MSG_HEADER header; 

MARK otherMark; // In; the other mark 

MARK_TOKEN otherToken; // In: the token to copy 

} MARK_POSITION_TOKEN, * P_MARK_POSITION_TOKEN; 

Comments If sent directly to mark: you only need to fill in the otherMark field, the mark will take care of the rest 

& will check to see that both marks point at the same component. Since you'd have no idea what the 
other Token is, this is the only sensible way to send this message (via msgMarkDeliver won't work). 

msgMarkPositionAtChild 

Asks a component to reposition the token to the given child component which is given as a UUID/UID 
pair. 

Takes P_MARK_POSITION_CHILD, returns STATUS. 

♦define msgMarkPositionAtChild MakeMsg (clsMark, 82) 

Arguments typedef struct MARK_POSITION_CHILD { 

MARK_MSG_HEADER header; 

MARK_COMPONENT child; // In: the child to position to; 

} MARK_POSITION_CHILD, * P_MARK_POSITION_CHILD; 

Comments The UID may be null if it is unknown, but the UUID will always be valid. 
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msgMarkPositionAtGesture 

Asks a component to reposition the token at the given gesture. 

Takes P_MARK_POSITION_GESTURE, returns STATUS. 

#define msgMarkPositionAtGesture MakeMsg(clsMark, 83) 

rgumersfs typedef struct MARK_POSITION_GESTURE { 

MARK_MSG_HEADER header; 
GWIN_GESTURE gesture; 
MARK_LOCATION location; 
} MARK_POSITION_GESTURE, * P_MARK_POSITION_GESTURE; 

ts The location parameter indicates how to position relative to the gesture. Note that there are a variety of 

location codes that might be or'd together. 



msgMarkPositionAtSelection 

Asks a component to reposition the token to the selection, which it presumably owns. 

Takes P_MARK_POSITION_SELECTION, returns STATUS. 
#define msgMarkPositionAtSelection MakeMsg(clsMark, 85) 

Arguments typedef struct MARK_POSITION_SELECTION { 

MARK_MSG_HEADER header; 
MARK_LOCATION location; 
} MARK_POSITION_SELECTION, * P_MARK_POSITION_SELECTION; 

Comments If the component doesn't own the selection, then return stsFailed. 

msgMarkNextChild 

Requests the component to move the token to the next child. 

Takes P_MARK_MESSAGE, returns STATUS. 

#define msgMarkNextChild MakeMsg(clsMark, 86) 

Message typedef struct MARK_MESSAGE { 

Arguments MARK_MSG_HEADER header; 

} MARK_MESSAGE, * P_MARK_MESSAGE; 

Comments If a child is found and the token moved to it, return stsMarkEnterChild, not stsOK. If return, the mark 

is likely (but may not) send msgMarkGetChild to find out who the child actually is. 

msgMarkGetChild 

Requests the component to fill in the component at the current token. 

Takes P_MARK_GET_CHILD, returns STATUS. 

#define msgMarkGetChild MakeMsg(clsMark, 90) 

Arguments typedef Struct MARK_GET_CHILD { 

MARK_MSG_HEADER header; 

MARK_COMPONENT child; //Out: fill in uid or uuids 

BOOLEAN childlsDoc; //Out: is the child is a document? 

BOOLEAN childlsOpen; //Out: is the child open? 

} MARK_GET_CHILD, * P_MARK_GET_CHILD; 

Comments This is sent because, presumable, the response to some other move message was stsMarkEnterChild. If 

the token doesn't point at a child, return stsFailed. 
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pArgs->childIsDoc should set true if the child is an embedded document. If the child is just an g 

embedded component that is to be considered part of the receiving component, then set this field false. £ 

This field is used by clsMark to determine if it should apply the markEnterMode bits that control < 

entering embedded documents (they don't control entering embedded components, this is always done.) £ 

If pArgs->childIsDoc is set true, then childlsOpen must be set to reflect the "open" status of the 
embedded doc. 

If your component is managing its own embedees, typically your component will only deal with the 
embedded instances of clsAppWin. These are components that are part of your component: you should 
set pArgs->childIsDoc to false (pArgs->childIsOpen doesn't matter in this case). When the appWin is 
entered, it will handle the proper reporting of the embedded document. (clsAppWin sets 
pArgs->childIsDoc to true and pArgs->childIsOpen appropriately.) 

msgMarkSelectTarget 

Requests the component to select the target data item. 

Takes P_MARK_MESSAGE, returns STATUS. 

#define msgMarkSelectTarget MakeMsg (clsMark, 89) 

message typedef struct MARK_MESSAGE { 

Arguments MARK_MSG_HEADER header; 

} MARK_MESSAGE, * P_MARK_MESSAGE; 

msgMarkShowTarget 

Request the component to return the window that contains the graphical view of the target. 

Takes P_MARK_SHOW_TARGET, returns STATUS. 

#define msgMarkShowTarget MakeMsg (clsMark, 88) 

Arguments typedef Struct MARK_SHOW_TARGET { 

MARK_MSG_HEADER header; 
WIN win; 

RECT32 rect; 

} MARK_SHOW_TARGET, * P_MARK_SHOW_TARGET; 

Comments The rectangle returned is the area within the window that encloses the target. 

Some components may not have a viewable representations of the target, in which case they can return 
stsMarkNoWin, or simply not implement this message. Other components may have a graphical view 
only part of the time. In this case, it should ensure that the target has a graphical representation, 
otherwise return stsMarkNoWin if the target isn't right now. 

Note that this message requests that the target be scrolled into view. That should be done by sending 
msgEmbeddedWinShowChild to the win showing the target (usually the win that is returned in 
pArgs->win). 
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msgMarkEnterChild 

Sent when a component requests the mark to enter a child (usually via returning stsMarkEnterChild to 
a message send with msgMarkDeliverNext). 

Takes P_MARK_MESSAGE, returns STATUS. 

#define msgMarkEnterChild MakeMsg (clsMark, 120) 
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fessage typedef Struct MARK_MESSAGE { 

Arguments MARK_MSG_HEADER header; 

} MARK MESSAGE, * P MARK MESSAGE; 



»omtwenfs 



This message sends msgMarkGetChild to the component to get the child at the token and then enters 
the child if appropriate. 

msgMarkEnterLevel 

Sent when a component requests the mark to bump up a level in its class chain, or when a position or 
next message fails and the mark tries the next class level. 

Takes P_MARK_MESSAGE, returns STATUS. 

#define msgMarkEnterLevel MakeMsg(clsMark, 121) 

Messoge typedef struct MARK_MESSAGE { 

Arguments MARK_MSG_HEADER header; 

} MARK_MESSAGE, * P_MARK_MESSAGE; 

Comments This message sends msgMarkGetDataAncestor to the component and resets the token. 

msgMarkEnterParent 

Sent when a component runs out of data altogether and the mark needs to move on (and up). 

Takes P_MARK_MESSAGE, returns STATUS. 

#define msgMarkEnterParent MakeMsg(clsMark, 122) 

Message typedef struct MARK_MESSAGE { 

MARK_MSG_HEADER header; 
} MARK_MESSAGE, * P_MARK_MESSAGE; 

This message may send msgMarkGetParent to the component to find out who the parent is. 

msgMarkGetToken 

Sent from one mark to another to get the other's token. 

Takes P_MARK_TOKEN, returns STATUS. 

#define msgMarkGetToken MakeMsg(clsMark, 123) 

typedef struct MARKJTOKEN { 

CLASS classLevel; // which class level is the data at 
U32 index; // index to the data item 

U32 index2; // secondary index if needed 

} MARKJTOKEN, * P_MARK_TOKEN; 

This is not intended to be used by clients of mark. 




PRFRAME.H 



This file contains the API for clsPrintFrame. 
clsPrFrame inherits from clsCustomLayout. 

Provides the page outline during printing. 

#ifndef PRFRAME_INCLUDED 
#define PRFRAME_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

#ifndef UID_INCLUDED 

♦include <uid.h> 

#endif 

#ifndef PRINT_INCLUDED 

♦include <print.h> 

♦endif 



Common #defines and typedefs 



Window Tags for Child Windows 



♦define tagPrFrameLeftHeader 
♦define tagPrFrameCenterHeader 
♦define tagPrFrameRightHeader 
♦define tagPrFrameLeftFooter 
♦define tagPrFrameCenterFooter 
♦define tagPrFrameRightFooter 
♦define tagPrFrameMarginWin 

♦ifndef NO_NEW 

♦ifndef prFrameNewFields 

♦include <clayout.h> 



MakeTag (clsPrFrame, 255) 

MakeTag (clsPrFrame, 254) 

MakeTag (clsPrFrame, 253) 

MakeTag (clsPrFrame, 252) 

MakeTag (clsPrFrame, 251) 

MakeTag (clsPrFrame, 250) 

MakeTag (clsPrFrame, 249) 



Messages 



msgNewDefaults 

Initializes the PRFRAME_NEW_ONLY structure to default values. 
Takes P_PRFRAME_NEW, returns STATUS. Category: class message. 

typedef PRINT_SETUP PRFRAME_NEW_ONLY, *P_PRFRAME_NEW_ONLY; 
♦define prFrameNewFields \ 

customLayoutNewFields \ 

PRFRAME_NEW_ONLY prFrame; 

typedef struct PRFRAME_NEW { 

p rF r ameNe wF i e 1 ds 
} PRFRAME NEW, *P PRFRAME NEW; 
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msgNewDefaults 

Initializes the default new arguments. 

Takes P_PRFRAME_NEW, returns STATUS. Category: class message. 

Messoge typedef struct PRFRAME_NEW { 

Argymenfs prFrameNewFields 

} PRFRAME_NEW, *P_PRFRAME_NEW; 

Comments no header or footer text 

headerMargin.top = 500 Mils 
headerMargin.left = 750 Mils 
headerMargin.right = 750 Mils 
headerMargin. bottom = Mils 
footerMargin.top = Mils 
footerMargindeft = 750 Mils 
footerMargin. right = 750 Mils 
footerMargin. bottom = 500 Mils 
mainMargin.top = 750 Mils 
mainMargindeft = 750 Mils 
mainMargin.right = 750 Mils 
mainMargin. bottom = 750 Mils 

msgNew 

Creates a new print frame object. 

Takes P_PRFRAME_NEW, returns STATUS. Category: class message. 

#endif 
#endif 

Messoge typedef struct PRFRAME_NEW { 

Arguments prFrameNewFields 

} PRFRAME NEW, *P PRFRAME NEW; 



msgPrFrameSend 

Sends the tagged window the message. 

Takes P_PRFRAME_SEND, returns STATUS. 

mts typedef struct PRFRAME_SEND { 

U32 tag; // window tag 

MESSAGE msg; // message to send 

P_ARGS pArgs; // arguments to pass 

SIZE0F lenSend; // argument length 

} PRFRAME_SEND, *P_PRFRAME_SEND ; 

#define msgPrFrameSend MakeMsg(clsPrFrame, 1) 

msgPrFrameSetup 

Sets the print frame values/fields to the setup information. 

Takes P_PPJNT_SETUP, returns STATUS. 

tdefine msgPrFrameSetup MakeMsg(clsPrFrame, 2) 



Arguments 



PRFRAME.H 
Messages 
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msgPrFrameExpand 

Expand any abbreviated labels for the current page/date/doc name. 

Takes P_PRFRAME_EXPAND, returns STATUS. 

typedef struct PRFRAME_EXPAND { 

char page [nameBuf Length ] ; // printing page number (pg.) 
char date [nameBuf Length ] ; // date string (dt.) 
char name [nameBuf Length ] ; // doc name (nm.) 
char reserved [nameBuf Length] ; 
PRFRAME EXPAND, *P PRFRAME EXPAND; 



} 

♦define msgPrFrameExpand 



MakeMsg(clsPrFrame, 3) 




LrfNH 
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PRINT.H 



This file contains the API for clsPrint. 

clsPrint inherits from clsApp. 

Provides a wrapper to guide PenPoint documents through the printing process. 

To print a document, the Application Framework creates a wrapper document (an instance of clsPrint) 

that embeds the document to be printed in itself. To print the document, the wrapper first opens the 

document to the printer (rather than to the screen). The wrapper then uses and instance of clsPrLayout 

to send printing-related messages to the document and any of its embedded documents. 

Developers: You should not subclass clsPrint. However, to support printing, your application needs to 

handle many of the messages defined by clsPrint. 



Pagination 



There are two basic styles of pagination: flow and nonflow. The printing wrapper sends 
msgPrintGetProtocols to a document to ask it what style of pagination it supports. 

For more information on pagination, please refer to the chapter on Printing in the PenPoint 
Architectural Reference. 



Option Cards for Printing 

The Application Framework provides a Print Setup option sheet, which allows the user to change 
margins and the running headers and footers that are printed with a document. 

If your application has other printing options that you want the user to change, you should add your 
option cards to the Print Setup sheet. To do so, your application should handle msgAppAddCards and 
should add your cards when the tag passed in is tagAppPrintSetupOptSheet. 

tifndef PRINT_INCLUDED 

#define PRINT_INCLUDED 

tifndef UUID_INCLUDED 

#include <uuid.h> 

tendif 

tifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

tendif 

tifndef GEO_INCLUDED 

tinclude <geo.h> 

tendif 

tifndef SYSFONT_INCLUDED 

tinclude <sysfont.h> 

tendif 

tifndef WIN_INCLUDED 

tinclude <win.h> 

tendif 

tifndef EMBEDWIN_INCLUDED 

tinclude <embedwin . h> 

tendif 
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Common #defines and typedefs 

Status Codes 

#define stsPrintErrorCheckPrinter MakeStatus(clsPrint, 1) 

Print Option Sheet Tags 



tdefine tagPrJobDialog 


MakeTag (clsPrint 


255) 


tdefine tagPrOption 


MakeTag (clsPrint 


254) 


#define tagPrPrinterLabel 


MakeTag (clsPrint 


253) 


tdefine tagPrEnabledLabel 


MakeTag ( cl sP r int 


252) 


#define tagPrPaperSizeLabel 


MakeTag (clsPrint 


251) 


♦define tagPrPagesLabel 


MakeTag (clsPrint 


250) 


tdefine tagPrStartingPageLabel 


MakeTag (clsPrint 


249) 


tdefine tagPrPrinter 


MakeTag (clsPrint 


128) 


tdefine tagPrStatus 


MakeTag (clsPrint 


140) 


#define tagPrEnabledOn 


MakeTag (clsPrint 


141) 


#define tagPrEnabledOff 


MakeTag (clsPrint 


142) 


tdefine tagPrPages 


MakeTag (clsPrint 


129) 


tdefine tagPrPagesAll 


MakeTag (clsPrint 


160) 


tdefine tagPrPagesRange 


MakeTag (clsPrint 


161) 


tdefine tagPrPagesFrom 


MakeTag (clsPrint 


162) 


tdefine tagPrPagesTo 


MakeTag (clsPrint 


163) 


tdefine tagPrPaperSize 


MakeTag (clsPrint 


131) 


tdefine tagPrPaperWidth 


MakeTag (clsPrint 


174) 


tdefine tagPrPaperHeight 


MakeTag (clsPrint 


175) 


tdefine tagPrStartingPage 


MakeTag (clsPrint 


132) 



Print Margins 

This structure Gontains the margjn oflsets (in Mils) measured from the top, bottom, left, and right edges of the paper. 



typedef struct PRINT_MARGINS { 

S32 top; 

S32 bottom; 

S32 left; 

S32 right; 
} PRINT MARGINS, *P PRINT MARGINS; 



// offset for top margin 
// offset for bottom margin 
// offset for left margin 
// offset for right margin 



Header and Footer Strings 



This structure contains the strings for either a header or a footer. 



typedef struct PRINT_HFDATA { 

U8 reserved; // 

char leftData[nameBufLength] ; // 

char centerData [nameBuf Length] ; // 

char rightData [nameBuf Length] ; // 

} PRINT HFDATA, *P PRINT HFDATA; 



reserved - must be 
string on left side 
string in center 
string on right side 



Print Setup 



This structure contains setup information for printing. 



typedef struct PRINT SETUP { 



OBJECT 

PRINT_MARGINS 

PRINT_MARGINS 

PRINT_MARGINS 

PRINT_HFDATA 

PRINT_HFDATA 

SYSDC_FONT_SPEC 

U16 



frame; 

mainMargins ; 
headerMargins ; 
f ooterMargins ; 
headerlnfo; 
footer Info ; 
font Spec; 
font Size; 



// reserved 

// print margins for the document 

// print margins for the header 

// print margins for the footer 

// strings to display in the header 

// strings to display in the footer 

// header/ footer font data 

// header/footer font size, in points 



} PRINT SETUP, *P PRINT SETUP; 
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Embeddee Print Info 

Users can decide: 



to not print an embedded document; 

to print the visible portion of an embedded document in the place in the parent document where it 
is embedded; 



♦ to print the entire embedded document at the end of the parent. 

This structure contains information for printing embedded documents. Note: expandlnPlace and 
printBorders are not currently implemented. 

typedef struct EMBEDDEE_PRINT_INFO { 



U16 expandlnPlace : 1; 

U16 expandAtEnd : 1/ 

U16 invisible : 1; 

U16 printBorders : 1; 

U16 reserved : 12; 

U16 reserved2 : 16; 



// TRUE to print entire contents in place 

// TRUE to print entire contents at end 

// FALSE to print visible portion in place 

// TRUE to not print 

// TRUE to show borders around the window 

// reserved 

// reserved 



} EMBEDDEE PRINT INFO, *P EMBEDDEE PRINT INFO; 



Spool mode values 



Note: Spooling is not implemented. 



tdefine prModeCopy 
tdefine prModeLock 



//to copy the doc for spooling 
//to lock the doc for spooling 



Print Metrics 



This structure defines the public instance data that clsPrint maintains for a document. You get a copy of 
this structure when you send msgPrintGetMetrics to a document. 



typedef struct PRINT METRICS 


[ 


U32 


reservedl; 




// 


U16 


pageRangeStart ; 




// 


U16 


pageRangeEnd; 




// 


U16 


start ingPage ; 




// 


U16 


copies; 




// 


U16 


collating: 


2 


// 


U16 


orientation: 


2 


// 
// 


U16 


pageAll : 


1 


// 


U16 


spoolMode : 


2 


// 


U16 


firstPageHeader 


:1 


// 


U16 


reserved2 : 


8 


// 


U8 


paperSizeType; 




// 


SIZE32 


paperSize; 




// 



PRINT_SETUP firstPageSetup; 
PRINT_SETUP pageSetup; 
char printer [nameBufLength] ; 

EMBEDDEE_PRINT_INFO embedding; 
U32 reservedData [ 6 ] ; 

PRINT METRICS, *P PRINT METRICS; 



reserved 

start page # (not used if pageAll is TRUE) 
end page # (not used if pageAll is TRUE) 
starting page # (to be printed on pages) 
not used 
not used 

either prOrientPortraitNormal or 
// pdOrientLandscapeNormal (see win.h) 
TRUE to print all pages 
see spool mode values 
TRUE to enable first page headers 
reserved 

Popular paper type (see clsPrn.h) 
Size of paper in Mils 

// not used 

// page setup information 

// name of printer to use 

// how to print embedded documents 

// reserved 



Print Embeddee Action 

This structure is used by msgPrintEmbeddeeAction and msgPrintExamineEmbeddee to pass 
information about the child being processed. 
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typedef struct PRINT_EMBEDDEE_ACTION { 
WIN embeddedWin; 

U16 action; 

EMBEDDEE_PRINT_INFO embedPrintlnfo; 
U32 reserved [3]; 



// embedded win to act on 

// proposed embeddee action flag 

// embeddee print properties 

// reserved 



} PRINT EMBEDDEE ACTION, *P PRINT EMBEDDEE ACTION; 



Embeddee Action Flags 



♦define prEmbedActionAsIs 

tdefine prEmbedActionExpandlnPlace 

♦define prEmbedActionExtract 



// visible part printed in place (default) 

1 // not supported 

2 // invisible or moved to end; either 
// way, child removed from parent 



Print Page 

This structure is used by msgPrintStartPage and msgPrintLayoutPage to pass information about what 
page needs to be printed next. 



typedef struct PRINT_PAGE { 

U16 pageNumber; 

U16 displayPageNumber; 

U16 logicalPageNumber; 

OBJECT jobUID; 

OBJECT appLayoutUID; 

U32 reserved [3]; 

} PRINT PAGE, *P PRINT PAGE; 



// In: tpages printed when this one is done 

// In: page number to display on page 

// In: ttimes msgPrintStartPage has been sent 

// In: print layout driver object 

// Out: obj to receive msgPrintEmbeddeeAction 

// reserved 



Messages 



Comments 



msgPrintStartPage 

Advance the document to its next logical page. 
Takes P_PRINT_PAGE, returns STATUS. 



#define msgPrintStartPage 
typedef struct PRINT PAGE { 



MakeMsg(clsPrint, 1) 



U16 


pageNumber; 


// 


In: 


U16 


displayPageNumber; 


// 


In: 


U16 


logicalPageNumber; 


// 


In: 


OBJECT 


jobUID; 


// 


In: 


OBJECT 


appLayoutUID; 


// 


Out 


U32 


reserved [3] ; 


// 


res 



tpages printed when this one is done 
page number to display on page 
ttimes msgPrintStartPage has been sent 
print layout driver object 
// Out: obj to receive msgPrintEmbeddeeAction 

} PRINT_PAGE, *P_PRINT_PAGE; 

This message is sent to a document as a signal to initialize its internal pagination data to a new page. 
When the document has no more pages to print it should return stsEndOfData in response to this 
message. Note: the document does not return stsEndOfData when it paginates its last page; it waits 
until the next time this message is sent (when it has no data left to paginate). If the document does have 
more pages to print, the following happens: 

♦ the document receives msgPrintGetProtocols. 

♦ the mainWin of document receives msgWinLayout at least once 

♦ the document receives msgPrintLayoutPage 
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tessage 
Vrgumenf 



Comments 



If appLayoutUID is objNull, the print layout driver will send any messages regarding embeddee actions 
(msgPrintEmbeddeeAction) to the document; otherwise it will send them to the appLayoutUID 
object set by the document in this structure. 

Developers: Your application should handle this message to support pagination. 



msgPrintLayoutPage 

Document lays out its logical page. 
Takes P_PRINT_PAGE, returns STATUS. 
tdefine msgPrintLayoutPage 



MakeMsg(clsPrint, 12) 



typedef struct PRINT_PAGE { 

U16 pageNumber; 

U16 displayPageNumber; 

U16 logicalPageNumber; 

OBJECT jobUID; 

OBJECT appLayoutUID; 

U32 reserved [3]; 
} PRINT PAGE, *P PRINT PAGE; 



// In: #pages printed when this one is done 

// In: page number to display on page 

// In: #times msgPrintStartPage has been sent 

// In: print layout driver object 

// Out: obj to receive msgPrintEmbeddeeAction 

// reserved 



The wrapper sends this message to the document after it sends msgPrintStartPage and 
msgPrintGetProtocols. This message can be thought of as a substitute for msgWinLayout. However, 
unlike msgWinLayout, it is sent only once per page. 

Developers: Your application should handle this message to support pagination. 



msgPrintGetMetrics 

Gets the applications print metrics. 

Takes P_PRINT_METRICS, returns STATUS. 

#define msgPrintGetMetrics MakeMsg(clsPrint, 2) 



typedef struct PRINT_METRICS { 



U32 


reservedl ; 




// 


D16 


pageRangeStart; 




// 


U16 


pageRangeEnd; 




// 


U16 


start ingP age; 




// 


U16 


copies; 




// 


U16 


collating: 


2; 


// 


U16 


orientation: 


2; 


// 
// 


U16 


page All : 


1; 


// 


U16 


spoolMode : 


2; 


// 


U16 


firstPageHeader 


:1; 


// 


U16 


reserved2 : 


8; 


// 


U8 


paperSizeType; 




// 


SIZE32 


paperSize; 




// 



PRINT_SETUP firstPageSetup; 
PRINT_SETUP pageSetup; 
char printer [nameBuf Length] ; 

EMBEDDEE_PRINT_INFO embedding; 
U32 reservedData [ 6 ] ; 

PRINT METRICS, *P PRINT METRICS; 



reserved 

start page # (not used if pageAll is TRUE) 
end page # (not used if pageAll is TRUE) 
starting page # (to be printed on pages) 
not used 
not used 

either prOrientPortraitNormal or 
pdOrientLandscapeNormal (see win.h) 
TRUE to print all pages 
see spool mode values 
TRUE to enable first page headers 
reserved 
// Popular paper type (see clsPrn.h) 
Size of paper in Mils 

// not used 

// page setup information 

// name of printer to use 

// how to print embedded documents 

// reserved 



You can send this message to OSThisAppO to get the current application's print metrics. During 
printing you can send this message to the jobUID (given in the pArgs of msgPrintStartPage) to get 
EFFECTIVE print metrics. EFFECTIVE print metrics are those from the original top-level document 
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in this print job. Deferred embedded documents print with effective margins, headers and footers, and 
orientation; the values in their own print metrics are ignored. 

Developers: Your application does not need to handle this message. 



iixjomerifs 



msgPrintSetMetrics 

Sets the application's print metrics. 

Takes P_PRINT_METRICS, returns STATUS. 

fdefine msgPrintSetMetrics MakeMsg(clsPrint, 3) 

typedef struct PRINT_METRICS { 

// reserved 

// start page # (not used if pageAll is TRUE) 

// end page # (not used if pageAll is TRUE) 

// starting page # (to be printed on pages) 

// not used 

// not used 

// either prOrientPortraitNormal or 

// pdOrient Lands capeNormal (see win.h) 

// TRUE to print all pages 

// see spool mode values 

// TRUE to enable first page headers 

// reserved 

// Popular paper type (see clsPrn.h) 

// Size of paper in Mils 
// not used 

// page setup information 
char printer [nameBuf Length] ; // name of printer to use 

EMBEDDEE_PRINT_INFO embedding; // how to print embedded documents 

U32 reservedData[6] ; // reserved 

} PRINT_METRICS, *P_PRINT_METRICS; 

You can send this message to OSThisAppO to set the current application's print metrics. 

Developers: Your application does not need to handle this message. 



U32 


reservedl; 


U16 


pageRangeStart ; 


U16 


pageRangeEnd; 


U16 


start ingP age ; 


U16 


copies; 


U16 


collating: 2; 


U16 


orientation: 2; 


U16 


pageAll: 1; 


U16 


spoolMode : 2 ; 


U16 


f irstPageHeader : 1 ; 


U16 


reserved2: 8; 


U8 


paperSizeType; 


SIZE32 


! paperSize; 


PRINT_ 


SETUP firstPageSetup; 


PRINT_ 


SETUP pageSetup; 



msgPrintApp 



Prints a document. 

Takes P_PRINT_DATA, returns STATUS. 

#define msgPrintApp 

typedef struct PRINT_DATA { 

OBJECT appUID; 

UUID appUUID; 

U32 reserved [2]; 

} PRINT DATA, *P PRINT DATA; 



MakeMsg(clsPrint, 4) 



// In: UID if this is the active app 
// In: application UUID 
// reserved 



This message prints the document. If you want to invoke printing, you send this message to 
thePrintManager, using ObjectSend or ObjectPost. 

Developers: Your application does not need to handle this message. 



msgPrintPaperArea 

Passes back the width and height of the printing area on the paper. 

Takes P_PRINT_AREA, returns STATUS.. 

tdefine msgPrintPaperArea MakeMsg(clsPrint, 7) 
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i typedef struct PRINT_AREA { g 

P_PRINT_METRICS pMetrics; // In: pNull or metrics for computation ^ 

SIZE32 area; // Out: size of print area, in Mils. jg 

} PRINT_AREA, *P_PRINT_AREA; g 

u. 

Comments thePrintManager returns the size of the printing area on a sheet of paper, adjusted to take into account g; 

margin values and interpreted relative to the orientation. Thus, thePrintManager swaps the computed ^ 

width and height values if the page orientation is landscape vs portrait. 

The size of the printing area is in Mils. It does not account for printer hardware limitations, i.e., the 
"unprintable area" on a page. 

You can send this message to thePrintManager at any time to get the the current document's printing 
area. You can either pass in the metrics from which to compute the area or set pMetrics = pNull. If 
pMetrics is pNull, thePrintManager will obtain the print metrics from theProcessResList. 

Developers: Your application does not need to handle this message. 



msgPrintGetProtocols 

Gets the pagination and embeddee printing protocols for the document. 

Takes P_PRINT_PROTOCOLS, returns STATUS. 

#define msgPrintGetProtocols MakeMsg(clsPrint, 9) 

typedef struct PRINT_PROTOCOLS { 

U16 paginationMethod; // Out: paginationMethod value 

U16 embeddeeSearch; // Out: embeddeeSearch value 

} PRINT_PROTOCOLS, *P_PRINT_PROTOCOLS ; 

The wrapper sends this message to the document after each msgPrintStartPage. 

Developers: Your application needs to handle this message and pass back the pagination method (see 
"paginationMethod Values" below) and the embeddee searching method (see "embeddeeSearch 
Values"). 



paginationMethod Values 



tdefine prPaginationTile 1 // tile pagination style 
#define prPaginationFlow 2 // flow pagination style 
#define prPaginationScale 3 // scale pagination style 



embeddeeSearch Values 



tdefine prEmbeddeeSearchByPrintJob 1 // print layout driver finds children 

// for the application 
tdefine prEmbeddeeSearchByApp 2 // app finds children while paginating 



msgPrintEmbeddeeAction 

Asks the document for permission to perform an action on an embeddee. 

Takes P_PRINT_EMBEDDEE_ACTION, returns STATUS. 
tdefine msgPrintEmbeddeeAction MakeMsg(clsPrint, 10) 

Message typedef struct PRINT_EMBEDDEE_ACTION { 

Arguments WIN embeddedWin ; // embedded win to act on 

U16 action; // proposed embeddee action flag 

EMBEDDEE_PRINT_INFO embedPrintlnfo; // embeddee print properties 

U32 reserved[3] ; // reserved 

} PRINT EMBEDDEE ACTION, *P PRINT EMBEDDEE ACTION; 
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Comments The wrapper sends this message to the (top-level) document being printed; it requests permission to 

perform an action on an embeddee. 

Developers: You should handle this message and return stsOK for yes, stsRequestDenied for no. 

In parameters: 

embeddedWin embedded win to act on 

action proposed embeddee action 

embedPrintlnfo embeddee print properties 

msgPrintExamineEmbeddee 

Sent to the print layout driver to interpret an embedded window's print properties. 
Takes P_PRINT_EMBEDDEE_ACTION, returns STATUS. 
#define msgPrintExamineEmbeddee MakeMsg(clsPrint, 11) 

message typedef struct PRINT_EMBEDDEE_ACTION { 

Arguments WIN embeddedWin; // embedded win to act on 

U16 action; // proposed embeddee action flag 

EMBEDDEE_PRINT_INFO embedPrintlnfo; // embeddee print properties 

U32 reserved[3]; // reserved 

} PRINT_EMBEDDEE_ACTION, *P_PRINT_EMBEDDEE_ACTION; 

Comments Documents that are being printed (or their layout objects) can send this message to the wrapper. It tells 

the print layout driver to interpret the embedded win's print properties and propose an action via 
msgPrintEmbeddeeAction. msgPrintEmbeddeeAction is sent subsequently even if no action is 
necessary. 

In parameters: 

embeddedWin embedded win to examine 

Out parameters: 

action proposed embeddee action 

embedPrintlnfo embeddee print properties 

Developers: You do not need to handle this message. 

msgPrintSetPrintableArea 

Sent to the printjob to adjust margins for the "unprintable area". 
Takes PRINTABLE_AREA, returns STATUS. 

#define msgPrintSetPrintableArea MakeMsg(clsPrint, 13) 

tdefine prAdjustActualForUnprintable flagO // make sure actual margins 

// account for hardware limits 

Arguments typedef struct PRINTABLE_AREA { 

U16 flags; 

PRINT_MARGINS printMetricsMargins; // user-set margins 
PRINT_MARGINS unprintableMargins; // hardware limitations 

PRINT_MARGINS actualMargins; // actual margins used by print 

// layout driver 
} PRINTABLE_AREA, *P_PRINTABLE_AREA; 

Comments A (top-level) document can send this to the printjob during printing as a request to adjust margins to 

account for printer hardware limitations (i.e., an unprintable area on the page). It affects only the 
current page. You typically first send msgPrintGetPrintableArea to get the margins that the printjob is 
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currently using. Then you can set the flags argument to prAdjustActualForUnprintable, and send the § 

structure on to this message. 



Automatic tiling by the printjob always adjusts the user-set (print metrics) margins to account for the 
unprintable area on the page. 

Typically graphics (non-flow) applications will desire this type of adjustment, while word processing 
(flow) apps won't since it may cause data reformatting. Sometimes, as with text, it is more user-friendly 
not to adjust (and let the data get clipped) so that the source of the problem is obvious to the user. Auto 
adjustment may induce unwanted visual changes and obscure their source. 

Developers: You do not need to handle this message. 

msgPrintGetPrintableArea 

Sent to the print job during printing to request margin information. 

Takes PRINTABLE_AREA, returns STATUS. 

#define msgPrintGetPrintableArea MakeMsg(clsPrint, 14) 

fessoge typedef struct PRINTABLE_AREA { 

U-ejumerifs U16 flags; 

PRINT_MARGINS printMetricsMargins; // user-set margins 

PRINT_MARGINS unprintableMargins; // hardware limitations 

PRINT_MARGINS actualMargins ; // actual margins used by print 

// layout driver 
} PRINTABLE_AREA, *P_PRINTABLE_AREA; 

Flags are ignored. 

Developers: You do not need to handle this message. 



£ 
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PRLAYOUT.H 



This file contains the API definition for clsPrLayout. 

clsPrLayout inherits from clsObject. 

A prLayout object makes a document paginate. 

A print layout object guides the top-level document through the pagination process and assists it in 

implementing its embeddees' print properties. 

#ifndef PRLAYOUT_INCLUDED 

tdefine PRLAYOUT_INCLUDED 

tifndef GO_INCLUDED 

#include <go.h> 

tendif 

tifndef UID_INCLUDED 

tinclude <uid.h> 

#endif 

tifndef PRINT_INCLUDED 

tinclude <print.h> 

tendif 



Common #defines and typedefs 



typedef struct PRLAYOUT_METRICS { 



OBJECT 
OBJECT 

OBJECT 
OBJECT 
OBJECT 
U32 



topLevelApp; 
current App; 

prFrame; 
winDev; 
print Job; 
reserved; 



// outermost document printed 

// current document being printed 

// as top-level 

// instance of clsPrFrame 

// printer is bound to this window device 

// "owner" of this object 



} PRLAYOUT METRICS, *P_PRLAYOUT_METRICS; 



Messages 



msgNew 

Create a new object. 

Takes P_PRLAYOUT_NEW, returns STATUS. 

guments typedef struct PRLAYOUT_NEW_ONLY { 

OBJECT topLevelApp; 

OBJECT prFrame; 

OBJECT winDev; 

OBJECT print Job ; 

U32 reserved; 

} PRLAYOUT_NEW_ONLY, *P_PRLAYOUT_NEW_ONLY; 

tdefine prLayoutNewFields \ 
objectNewFields \ 

PRLAYOUT_NEW_ONLY prLayout; 

typedef struct PRLAYOUT_NEW { 

prLayoutNewFields 
} PRLAYOUT NEW, *P PRLAYOUT_NEW; 



214 PENPOINT API REFERENCE 

Part 2 / PenPoint Application Framework 

msgPrLayoutGetMetrics 

Get PrLayout metrics. 

Takes P_PRLAYOUT_METRICS, returns STATUS. 

fdefine msgPrLayoutGetMetrics MakeMsg(clsPrLayout, 1) 

Message typedef struct PRLAYOUT_METRICS { 

Arguments OBJECT topLevelApp; // outermost document printed 

OBJECT current App; // current document being printed 

// as top-level 
OBJECT prFrame; // instance of clsPrFrame 
OBJECT winDev; // printer is bound to this window device 
OBJECT printJob; // "owner" of this object 
U32 reserved; 
} PRLAYOUT_METRICS, *P_PRLAYOUT_METRICS; 

msgPrLayoutSetMetrics 

Set PrLayout metrics. 

Takes P_PRLAYOUT_METRICS, returns STATUS. 

fdefine msgPrLayoutSetMetrics MakeMsg(clsPrLayout, 2) 

Message typedef struct PRLAYOUT_METRICS { 

// outermost document printed 

// current document being printed 

// as top-level 

// instance of clsPrFrame 

// printer is bound to this window device 

// "owner" of this object 

} PRLAYOUT_METRICS, *P_PRLAYOUT METRICS; 

msgPrLayoutNextPage 

Get next page. 

Takes PRLAYOUT_PAGE, returns STATUS. 

#define msgPrLayoutNextPage MakeMsg(clsPrLayout, 3) 

typedef struct PRLAYOUT_PAGE { 

U16 pageNumber; // In: paper sheets 

U16 displayPageNumber; // In: number displayed on page 

U16 logicalPageNumber; // Out: num times msgPrintStartPage sent 

OBJECT currentApp; // Out: top level app supplying current page 

BOOLEAN appChanged; // Out: true if first page from currentApp 

} PRLAYOUT_PAGE, *P_PRLAYOUT_PAGE; 

Uses print protocol messages defined in print.h to get the next page from the document being printed. 



OBJECT 


topLevelApp; 


OBJECT 


currentApp; 


OBJECT 


prFrame; 


OBJECT 


winDev; 


OBJECT 


printJob; 


U32 


reserved; 
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PRMARGIN.H 



This file contains the API for clsPrMargin. 
clsPrMargin inherits from clsWin. 

Provides clipping of children. 

tifndef PRMARGIN_INCLUDED 

#define PRMARGIN_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

tendif 

tifndef UID_INCLUDED 

tinclude <uid.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

tinclude <clsragr.h> 

#endif 

tifndef CLAYOUT_INCLUDED 

tinclude <clayout.h> 

tendif 

Common #defines and typedefs 

msgNew 

Create a new object. 

Takes P_PRMARGIN_NEW, returns STATUS. 

typedef struct PRMARGIN_NEW_ONLY { 

OBJECT client; // object to adjust layout 

} PRMARGIN_NEW_ONLY, *P_PRMARGIN_NEW_ONLY; 

tdefine prMarginNewFields \ 

customLayoutNewFields \ 

PRMARGIN_NEW_ONLY prMargin; 

typedef struct PRMARGIN_NEW { 

prMarginNewFields 
} PRMARGIN_NEW, *P_PRMARGIN_NEW; 

The prmargin object handles msgCstmLayoutGetChildSpec and then sends it on to the client for 
adjustment of default layout behavior. 



msgPrMarginSetMetrics 

Set the prMargin metrics. 

Takes P_PRMARGIN_METRICS, returns STATUS. 

typedef struct PRMARGIN_METRICS { 

OBJECT client; 
} PRMARGIN_METRICS, *P_PRMARGIN_METRICS ; 
tdefine msgPrMarginSetMetrics MakeMsg (clsPrMargin, 1) 
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RCAPP.H 



This file contains the API definition for clsRootContainerApp. 

clsRootContainerApp inherits from clsApp. 

Abstract class for root containers. 

This class defines the API for all root container applications. Root containers are expected to respond to 
this API as part of their implementation. 

PenPoint includes one implementation of a root container: the notebook. The messages defined in this 
class allow programatic control of a root container application. 

To get the uid of the root container of interest use msgAppGetRoot (see app.h) or msgAppMgrGetRoot 
(see appmgr.h). 

#ifndef RCAPP_INCLUDED 
tdefine RCAPP_INCLUDED 

♦include <clsmgr.h> 
tinclude <uuid.h> 

Common #defines and typedefs 

typedef OBJECT RCAPP, *P_RCAPP; 

Messages 

Sequential Access Messages 

The next four messages provide sequential access to documents within the target root container. 

msgRCAppNextDoc 

Increments a root container's internal pointer to the next document. 

Takes nothing, returns STATUS. 

tdefine msgRCAppNextDoc MakeMsg (clsRootContainerApp, 1) 

menfs This message is sent to a root container to cause it to move to the next page. This message does not 

actually cause the page turn to occur. After one or more msgRCAppNextDoc, you must send 
msgRCAppExecuteGotoDoc to actually force the page turn to happen. 

msgRCAppPrevDoc 

Decrements a root container's internal pointer to the previous document. 

Takes nothing, returns STATUS. 

tdefine msgRCAppPrevDoc MakeMsg (clsRootContainerApp, 2) 
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Comments This message is sent to a root container to cause it to move to the previous page. This message does not 

actually cause the page turn to occur. After one or more msgRCAppPrevDoc, you must send 
msgRCAppExecuteGotoDoc to actually force the page turn to happen. 



msgRCAppExecuteGotoDoc 

Turns a root container to the page pointed to by its internal pointer. 
Takes nothing, returns STATUS. 

#define msgRCAppExecuteGotoDoc MakeMsg(clsRootContainerApp, 3) 

Comments Send this message after a series of msgRCAppNextDoc or msgRCAppPrevDoc calls to force the page 

turn to happen. 

msgRCAppCancelGotoDoc 

Resets a root container s internal pointer to the current document. 

Takes P_UUID, returns STATUS. 

#define msgRCAppCancelGotoDoc MakeMsg(clsRootContainerApp, 4) 

Comments Send this message after a series of msgRCAppNextDoc or msgRCAppPrevDoc calls to cancel the calls 

reset the root contaner's internal pointer to the current page. 

$fr Random Access Messages 

The next two messages provide random access to documents within the target root container. 

msgRCAppGotoContents 

Turns a root container to its contents page. 
Takes nothing, returns STATUS. 

#define msgRCAppGotoContents MakeMsg(clsRootContainerApp, 5) 

Comments Send this message to a root container to force it to turn to its table of contents. 



msgRCAppGotoDoc 

Turns a root container to a document, or floats the document over the current page. 

Takes P_RCAPP_GOTO_DOC, returns STATUS. 

#define msgRCAppGotoDoc MakeMsg(clsRootContainerApp, 6) 

Arguments typedef struct RCAPP_GOTO_DOC { 

BOOLEAN gotoDoc; // True=turn to, False=float. 

UUID docUUID; // UUID of target document. 

UUID reservedl; // Reserved. 

U32 reserved2[2]; // Reserved, 

char reserved3 [nameBuf Length] ; // Reserved. 

U32 reserved4 [4] ; // Reserved. 

} RCAPP_GOTO_DOC, *P_RCAPP_GOTO_DOC ; 

Comments Send this message to a root container to turn to or float a document. The specified document must be 

within the root container. 
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VIEW.H 



This file contains the API definition for els View. 

clsView inherits from clsCustomLayout. 

clsView is an abstract class that defines an association between a data object and a view onto that data. 

Since clsView is an abstract class it should never be directly instantiated. 

tifndef VIEW_INCLUDED 
tdefine VIEW_INCLUDED 

#ifndef CLAYOUT_INCLUDED 
#include <clayout.h> 
#endif 



Common #defines and typedefs 



typedef OBJECT VIEW, *P VIEW; 



Messages 



msgNew 

Creates a new view. 

Takes P_VIEW_NEW, returns STATUS. Category: class message. 



// Data object to view. 

// Auto-create data object? 



typedef struct VIEW_NEW_ONLY { 

OBJECT dataObject; 

BOOLEAN createDataObject; 

} VIEW_NEW_ONLY, *P_VIEW_NEW_ONLY; 

tdefine viewNewFields \ 

customLayoutNewFields \ 

VIEW_NEW_ONLY view; 

typedef struct VIEW_NEW { 

viewNewFields 
} VIEW_NEW, *P_VIEW_NEW; 

If pArgs->view.dataObject is non-null, the new view object becomes an observer of the data object. 

clsView does not act on the value of pArgs->view.createDataObject. It is up to descendants of clsView 
to act on this field, typically by creating a new data object if the field is true. This behavior may not be 
appropriate of all descendants, however. 

Descendants: You should never handle msgNew directly. Instead, handle msglnit by initializing your 
instance data. The ancestor must be called before your msglnit handler. 

msgNewDefaults 

Initializes the VIEWJSTEW structure to default values. 

Takes P_VIEW_NEW, returns STATUS. Category: class message. 
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sage typedef struct VIEW_NEW { 

viewNewFields 
} VIEW_NEW, *P_VIEW_NEW; 

In response to this message, els View does the following: 

pArgs->embeddedWin.style.embeddor = true; 

pArgs->embeddedWin. style. embeddee = true; 

pArgs->view.dataObject = objNull; 

pArgs->view.createDataObject = false; 

Descendants: You should handle msgNewDefaults by initializing your _NEW structure to default 
values. The ancestor must be called before your handler. 

msgFree 

Defined in clsmgr.h. 

Takes OBJ_KEY, returns STATUS. 

Comments In addition to standard msgFree behavior, the view removes itself as an observer of its data object. It 

does NOT send msgFree to the data object. 

Descendants: You should handle msgFree by destroying all objects and resources you have created. It 
may be appropriate for you to destroy the data object if your view is the only observer of it. The ancestor 
must be called after your handler. 

msgSave 

Defined in clsmgr.h. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments In response to this message, the view sends msgResPutObject to pArgs->file with the data object as the 

value of pArgs. In effect, this means that saving the view also saves the data object. (If the data object is 
null, this writes the "null object" id into the resource file.) 

Descendants: You should handle msgSave by saving your instance data. The ancestor must be called 
before your handler. 

msgRestore 

Defined in clsmgr.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments In response to this message, the view sends msgResGetObject to pArgs->file. In effect, this means that 

restoring the view also restores the data object. (If the data object was null when the view was saved, the 
data object is null after msgRestore is handled.) 

If the restored data object is non-null, the view becomes an observer of the data object. 

Descendants: You should handle msgSave by restoring your instance data. The ancestor must be called 
before your handler. 
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Messages 

msgFreePending 

Defined in clsmgr.h. 

Takes OBJECT, returns STATUS. 

smments If the object being freed is the view's data object, the view sets its data object to objNull. 

Descendants: If you maintain instance data on the data object, you may need to handle this message by 
updating your instance data to reflect the impending destruction of the data object. The ancestor should 
be called before your handler. It is recommended, however, that your view not keep any information on 
the data object, thus maintaining a strict view/ data separation. In such cases, you will not need to handle 
msgFreePending. 

msgViewSetDataObject 

Specifies a view's data object. 

Takes OBJECT, returns STATUS. 

fdefine msgViewSetDataObject MakeMsg(clsView, 1) 

If the current data object is non-null, the view removes itself as an observer of the current data object. 
It then sets the current data object to pArgs and, if the new data object is non-null, becomes an observer 
of it. 

Descendants: If you maintain instance data on the data object, you may need to handle this message by 
updating your instance data to reflect the changed data object. The ancestor may be called before or 
after your handler. It is recommended, however, that your view not keep any information on the data 
object, thus maintaining a strict view/data separation. In such cases, you will not need to handle 
msgViewSetDataObject. 

msgViewGetDataObject 

Passes back a view's current data object 

Takes P_OBJECT, returns STATUS. 

tdefine msgViewGetDataObject MakeMsg(clsView, 2) 

Descendants: You do not normally handle this message. 
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BITMAP.H 



This file contains the API for clsBitmap. 

clsBitmap inherits from clsObject. 

Support class for clslcon (see icon.h). Serves as data object for the Bitmap Editor. Based on cached 
images (see sysgraf.h). 

clsBitmap takes a sampled image description, and optionally a mask, and a hotspot. It will file this 
description. It also provides messages to modify the bitmap appearance. The Bitmap Editor treats 
bitmaps as data objects. It creates a bitmap, files it, and will export it as resource file. This resource file 
can be processed further by SDK utility programs (see resappnd). 

A bitmap will prepare an argument structure for use by msgDcCachelmage so that the sampled image 
data in the bitmap can be converted to a cached image for quick rendering. See 
msgBitmapCachelmageDefaults. 

tifndef BITMAP_INCLUDED 
#define BITMAP_INCLUDED 

tifndef SYSGRAF_INCLUDED 
#include <sysgraf .h> 
#endif 



Typedefs, #defines, and Status Values 



#define bitmapResId 

tdefine bmEncodeNone 
tdefine bmEncodeRunLength 
#define bmEncodelBPS 
tdefine bmEncode2BPS 
tdefine bmEncode4BPS 
tdefine bmEncode8BPS 
tdefine bmEncodel6BPS 
tdefine bmEncode24BPS 
tdefine bmMono 
tdefine bmColorMap 
tdefine braDirectColor 

typedef struct BITMAP_STYLE 
{ 



U16 pixEncoding 
maskEncoding 
colorEncoding 
version 



4, 
4, 
3, 
5; 



MakeTag (clsBitmap, 



// 
// 
// 
// 
// 
// 
// 
// 

// 
// 
// 



1) 

no data 

run length encoded 

1 bit per sample 

2 bits per sample 
4 bits per sample 
8 bits per sample 
unused (reserved) 
unused (reserved) 

default 

Not Working (reserved) 

Not Working (reserved) 



// currently 



} BITMAP STYLE, *P BITMAP STYLE; 
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Messages 



msgNew 

Creates a bitmap. 

Takes P_BITMAP_NEW, returns STATUS. Category: class message. 

typedef struct BITMAP_NEW_ONLY 
{ 

BITMAP_STYLE style; // overall style 

SIZE16 size; // # of source samples 

P_U8 pPixels; // actual samples 

P_U8 pMask; // mask (must be bmEncodelBPS) or pNull 

XY16 hot Spot; // lower-left corner relative hot spot 

U32 spare 1; 

U32 spare2; 

} BITMAP_NEW_ONLY, *P_BITMAP_NEW_ONLY, 

BITMAP_METRICS, *P_BITMAP_METRICS; 

tdefine bitMapNewFields \ 
objectNewFields \ 
BITMAP_NEW_ONLY bitmap; 

typedef struct BITMAP_NEW 
{ 

bitMapNewFields 
} BITMAP_NEW, *P_BITMAP NEW; 

msgNewDefaults 

Initializes the BITMAP_NEW structure to default values. 

Takes P_BITMAP_NEW, returns STATUS. Category: class message. 

Message typedef struct BITMAP_NEW 

Arguments { 

bitMapNewFields 
} BITMAP_NEW, *P_BITMAP_NEW; 

bitmap. style. pixEncoding = bmEncode8BPS; 
bitmap. style. maskEncoding = bmEncodelBPS; 
bitmap . style . colorEncoding = bmMono; 



bitmap . style . version 


= 0; 


bitmap. size. w 




= 0; 


bitmap. size. h 




= 0; 


bitmap . pPixels 




= pNull; 


bitmap. pMask 




= pNull; 


bitmap. hotSpot 


X 


= 0; 


bitmap. hotSpot 


y 


= 0; 



msgBitmapGetMetrics 

Gets bitmap metrics. 

Takes P_BITMAP_GET_METRICS, returns STATUS. 

tdefine msgBitmapGetMetrics MakeMsg(clsBitmap, 0) 

msgBitmapSetMetrics 

Sets bitmap metrics. 

Takes P_BITMAP_METRICS, returns STATUS. 

tdefine msgBitmapSetMetrics MakeMsg(clsBitmap, 1) 



BITMAP. H 22T 

Messages sent to observers 



msgBitmapSetSize 



Sets bitmap size, resizing heap block if necessary. ^ 

a. 

Takes P_SIZE16, returns STATUS. t 

O 

tdefine msgBitmapSetSize MakeMsg(clsBitmap, 2) «8 

o 

o 
z 



msgBitmapInvert 

Inverts the colors of the bitmap. 
Takes nothing, returns STATUS. 
tdefine msgBitmapInvert MakeMsg(clsBitmap, 3) 



CO 



msgBitmapLighten 

Lightens the colors of the bitmap by 1/4. 

Takes nothing, returns STATUS. 

tdefine msgBitmapLighten MakeMsg(clsBitmap, 4) 

msgBitmapFill 

Fills bitmap pixels with RGB value leaving mask alone. 

Takes RGB value, returns STATUS. 

tdefine msgBitmapFill MakeMsg(clsBitmap, 6) 



msgBitmapCachelmageDefaults 

Prepares argument structure for msgDcCachelmage. 

Takes P_SYSDC_GACHE_IMAGE, returns STATUS. 

tdefine msgBitmapCachelmageDefaults MakeMsg(clsBitmap, 43) 

Comments After sending this message to the bitmap, pArgs is ready to be sent to a DC via usin^ 

msgDcCachelmage (see sysgraf.h). 

|F Messages sent to observers 

msgBitmapPixChange 

Sent to observing objects if a pixel is dirty. 

Takes P_BITMAP_PIX_CHANGE, returns STATUS. Category: observer notification. 

tdefine msgBitmapPixChange MsgNoError(MakeMsg(clsBitmap, 5)) 

Arguments typedef struct BITMAP_PIX_CHANGE 

{ 

XY16 pix; 

OBJECT sourceObject; 

P_BITMAP_METRICS pBitmap; 
} BITMAP PIX CHANGE, *P BITMAP PIX CHANGE; 



228 PENPOINT API REFERENCE 

Part 3 / Windows and Graphics 



msgBitmapChange 

Sent to observing objects if bitmap has changed. 

Takes nothing, returns STATUS. Category: observer notification. 

#de fine msgBitmapChange MsgNoError (MakeMsg(clsBitmap, 10)) 



msgBitmapMaskChange 

Sent to observing objects if bitmap's mask has changed. 

Takes nothing, returns STATUS. Category: observer notification. 

Idefine msgBitmapMaskChange MsgNoError (MakeMsg(clsBitmap, 11)) 
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CCITT.H 



CCITT Fax Group 3, one-dimensional data encoding and decoding routines. The functions described 
in this file are contained within CCITT.LIB. 



#ifndef CCITTJENCLUDED 
#define CCITT_INCLUDED 
typedef struct ENC0DE31 
{ 



U16 


pixCnt; 


// In: 


BOOLEAN 


photoNegative; 


// In: 

II 

II 


P_U8 


pScanLine; 


II In: 

II 

II 


BOOLEAN 


writeEol; 


II In: 
II 


BOOLEAN 


writeRtc; 


II In: 
II 


P_U8 


pOutBuf; 


II In: 
II 
II 
II 


U16 


inBitPos; 


II In: 
II 


P U8 


pOutLast ; 


II Out: 


U16 


byteUsed; 


// Out: 
II 


U16 


outBitPos; 


II out: 
II 



} ENC0DE31, *P_ENC0DE31; 

#define ccittDecodeToPacked 
tdefine ccittDecodeToRunLen 
#define ccittDecodeToGroup3_lD 

typedef struct DEC0DE31 
{ 



S16 
S16 
BOOLEAN 

BOOLEAN 



BOOLEAN 

P_U8 

U16 

S16 
P U8 



format; 
pixCnt; 
readEolRtc; 

photoNegative; 



newLine; 

plnBuf; 

inBitPos; 

inBufSz; 
pOutBuf; 



// Structure for use by function CcittEncode31 



How many pixels in the scanline. 
Input bitmap's palette: 
true: = white, 1 = black, 
false: 1 = white, = black. 
Scanline data to encode. 
Note: A scanline must be 

a multiple of words. 
EOL code is to be written at 
the beginning of the scanline. 
6 EOLs are to be written at 
the end of the scan line. 
Starting byte at which to put data. 
The buffer size must accomodate a 
worst case encoding for one scanline. 
2*pixCnt, +2 w/EOL, +9 w/RTC. 
Bit # in pOutBuf to start encoding 
Bit = MSB, Bit 7 = LSB 
Last byte where data was put 
Number of bytes used for encoding, 
including the last partial byte. 
Bit # in pOutLast where last bit 
was put + 1. 



// Decode to Packed bitmap. 

1 // Decode to sample image operator Run-Length. 

2 // Decode to Group 3 1-Dimension fax encoding. 

// Structure for use by fuction CcittDecode31 



// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 



in: ccittDecodeToPacked, RunLen, or Group3_lD. 
in: How many pixels comprise a scanline. 
in: EOL or RTC string is to be read 

at the end of each scanline. 
in: Output palette: 

true: = white, 1 = black 

false: 1 = white, = black, 
in/out: Must be set to true at the 

start of each scanline and left 
alone for remainder of scanline. 
in: Input buffer: 

Starting byte of data to decode. 

Bit # in plnBuf to start decoding. 

Bit = MSB, Bit 7 = LSB 

# of data bytes within input buffer. 

Output buffer: 

This field should be initialized once 

at the beginning of each scanline and 

left alone for the rest of the line. 

The size of the output buffer must 



in: 
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S16 

BOOLEAN 
BOOLEAN 
P_U8 

S16 

S16 

BOOLEAN 
S16 
S16 

BOOLEAN 
S16 
} DEC0DE31, 



decodedSz; 

done; 

rtcRead; 

plnLast; 

lastBitPos; 

outBitPos; 



curlsO; 
nDecoded; 
nEolRead; 
resyncToNextEol; // 
adjacent Zeros; // 
*P DEC0DE31; 



accomodate for the worst case decoding 

pixCnt for decodeToRunLength, 

2* ((pixCnt+15)/16) for ccittDecodeToPacked, 

( (9*pixCnt)/16)+2 for ccittDecodeToGroup3_lD . 
out: The number of bytes of decoded output 

placed into *pOutBuf. 
out: A complete scanline has been decoded, 
out: RTC detected (6 consecutive EOLs) . 
out: Points to last data byte within 

*pInBuf that was decoded, 
out: Next bit # within *pInLast byte 

that will be decoded, 
private: Bit # within pOutBuf at which next 

bit of decoded data will be placed, 
private: Last run was zero bits/pixels, 
private: # of scanline pixels decoded, 
private: # of EOLs read with scanline. 
private: Resync to next EOL - data error, 
private: Consecutive zero bit run count. 



CcittEncode31 

Encode one scanline of a packed bitmap into fax group 3 T.4 1-D format. 

Returns nothing. 

void EXPORTED CcittEncode31 ( 
P_ENC0DE31 pEncode ); 



CcittDecode31 

Decode one scanline worth of fax group 3 T.4 1-D image data. 
Returns BOOLEAN. 

Function Prototype BOOLEAN EXPORTED CcittDecode31 ( 
P_DEC0DE31 pDecode ); 

Output can be either the packed bitmap format, sampled image operatorlength encoded format, or 

Group 3 1 dimensional image format without. Function returns true if successful, false if the input 

datanot valid fax data. The interface to this function is such thatcalls may be needed to decode a 

complete scanline. As such,states are kept in the interface structure. Fields labeledprivate are not to 

be molested by the caller. 

Example of decoding a TIFF CCITT/3 image (where there is no EOL or RTCand the number of 
scanlines is known a priori, using a decodedof our run length format: 



= ccittDecodeToRunLen; 
= 1024; 
= false; 



decode . format 
decode . pixCnt 
decode . readEolRtc 

for (all scanlines) 
{ 

decode . inBitPos = 0; 

decode. pOutBuf = whatever; 

decode. plnBuf = whatever; 

decode . inBufSz = whatever; 

decode . newLine = true; 

while (true) 
{ 

if (!CcittDecode31(&decode)) 
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break; // the input data is screwed up. 

if (decode. done) 

break; // done decoding current scanline. J5 

z 

CL 

// Supply new bits for next call. Note that there may be < 

II partial bits left undecoded within the last decoded byte. © 

// The next call to decode must start with any undecoded bits. °* 

/ If you buffer the source bits, then copy all undecoded bits ^ 

// into the new buffer. The plnLast and lastBitPos fields tell O 

// you the amount left undecoded. Z 

decode. plnBuf = plnLast; // Or your new buffer, 

decode. inBufSz = whatever; // # of bytes w/in buffer, 

decode . inBitPos = decode. lastBitPos; // Assuming that you copy 

// . *decode. plnLast to new 

} // buffer. 

// Done decoding a scanline. 

} 
Example of decoding a raw fax input where there is EOLs and RTCand the number of scanlines is not 
known a priori, using aformat of packed bit output: 

decode . format = ccittDecodeToPacked; 

decode . inBitPos = 0; 

decode.pInBuf = whatever; 

decode. inBufSz = whatever; 

decode. readEolRtc = true; 

decode . rtcRead = false; 

while ( ! decode . rtcRead) 
{ 

decode . newLine = true; 

decode. pOutBuf = whatever; 

decode. pixCnt = whatever; // # of pixels of packed data 

// *pOutBuf can accomodate, 
while (true) 
{ 

if ( !CcittDecode31 Udecode) ) 

break; // the input data is screwed up. 

if (decode. done) 

break; // done decoding current scanline. 

// Supply new bits for next call. Note that there may be 

// partial bits left undecoded within the last decoded byte. 

// The next call to decode must start with any undecoded bits. 

/ If you buffer the source bits, then copy all undecoded bits 

// into the new buffer. The plnLast and lastBitPos fields tell 

// you the amount left undecoded. 

decode.pInBuf = plnLast; // Or your new buffer, 

decode. inBufSz = whatever; // # of bytes w/in buffer, 

decode . inBitPos = decode. lastBitPos; // Assuming that you copy 

// *decode. plnLast to new 

} // buffer. 

// Done decoding a scanline. 
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GEO.H 



This file contains the API definition for PenPoint's geometry package. The package provides points, 
rectangles, matrices, etc., and is used by the graphics and windowing software. 

Typical application software will only need the types defined in this file and not need to use the 
functions. 

The functions described in this file are contained in WIN.LIB. 

tifndef GEO_INCLUDED 
#define GEO_INCLUDED 
fifndef GO_INCLUDED 
tinclude <go.h> 
#endif 



Typedefs, #defines, and Status Values 



typedef S32 COORD32; 
typedef SI 6 C00RD16; 
typedef SI 6 ANGLE; 

typedef struct 



FIXED 



} SCALE, * P_SCALE; 
typedef struct 

{ 
COORD32 x, 

y; 

} XY32, * PJCY32; 
typedef struct 
{ 

COORD32 w, 
h; 
} SIZE32, * P_SIZE32; 

typedef struct 

{ 

XY32 origin; 

SIZE32 size; 

} RECT32, * P_RECT32; 

typedef struct 
{ 
C00RD16 x, 

y; 

} XY16, * P_XY16; 
typedef struct 
{ 
C00RD16 w, 
h; 
} SIZE16, * P SIZE16; 



// Foley/VanDam counter clockwise angles 



234 PENPOINT API REFERENCE 

Part 3 / Windows and Graphics 

typedef struct 
{ 

XY16 origin; 

SIZE16 size; 
} RECTI 6, * P_RECT16; 

Type MAT represents a 3x3 matrix; however ml 3, m23 and m33 are constant and so they are not 
stored. 



mil 


ml2 


ml3 f 


m21 


m22 


m23 


m31 


m32 


m33 


sX 


a 





a 


sY 





tx 


tY 


1 


typedef 


struct 





FIXED mil, 

ml2, 

m21, 

m22; 

S32 m31, 

m32; 

} MAT, * P_MAT; 

Enuml6 (GEO_MAT_MULT) {geoPreMultiply, geoPostMultiply} ; 



Handy macros 



tdefine Coord32Tol6(c) ( (c>0) ? (COORDl6)Min(c,maxSl6) : (COORD16)Max(c,minS16) ) 
#define Coordl6from32(c) Coord32Tol6 (c) 
tdefine Rectlnit(r, _x, _y, _w, _h) \ 

{ (r) ->origin.x = (_x) ; (r) ->origin.y = (_y) ; \ 

(r)->size.w = (_w) ; (r)->size.h = (_h) ; } 
tdefine RectRight(r) ( (r) ->origin.x + (r)->size.w) 
tdefine RectTop(r) ( (r)->origin.y + (r)->size.h) 

Functions 

RectlCTo32 

Take a RECTI 6 and produce a RECT32. 

Returns nothing. 

jrsefiors Prototype void EXPORTED Recti 6To32 ( 
P_RECT32 p32, // Out 
P_RECT16 pi 6 //In 
); 

Rect32Tol6 

Take a RECT32 and produce a RECTI 6 with rounding. 

Returns nothing. 

void EXPORTED Rect32Tol6 ( 
P_RECT16 pi 6, //Out 
P_RECT32 p32 // In 

); 

Each 32-bit number is rounded to 16-bits using Coord32Tol6. 
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Functions 



Rect32Intersect 

Take two RECT32's and produce their intersection. 



Returns BOOLEAN. g 

o 

Function Prototype BOOLEAN EXPORTED Rect 32 Intersect ( * 

P_RECT32 pA, //In 5 

P_RECT32 pB, //In § 

P_RECT32 pRet // Out: the intersection £ 

); 

Comments Returns whether the two rectangles intersect. When TRUE, the rectangle returned will always have 

positive width and height, even though either of the parameter rectangles may have negative width or 
height. 

Rect32slntersect 

Test if two RECT32's intersect. 

Returns BOOLEAN. 

BOOLEAN EXPORTED Rect32slntersect ( 
P_RECT32 pA, //In 

P_RECT32 pB //In 

); 

Either of the parameter rectangles may have negative width or height. 



Rect32EnclosesRect32 

Test if a RECT32 encloses another RECT32. 
Returns BOOLEAN. 

Function Prototype BOOLEAN EXPORTED Rect32EnclosesRect32 ( 
P_RECT32 pA, //In 

P_RECT32 pB // In 

); 

Comments Returns true if rect A completely encloses rect B. Either of the parameter rectangles may have negative 

width or height. 

Rectl6Intersect 

Take two RECTI 6's and produce their intersection. 
Returns BOOLEAN. 

Function Prototype BOOLEAN EXPORTED Rectl6lntersect ( 
P_RECT16 pA, //In 

P_RECT16 pB, //In 

P_RECT16 pRet // Out: the intersection 
); 

Comments Returns whether the two rectangles intersect. When TRUE, the rectangle returned will always have 

positive width and height, even though either of the parameter rectangles may have negative width or 
height. 
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Test if an XY32 point is inside a RECT32. 
Returns BOOLEAN. 

icriort Prototype BOOLEAN EXPORTED XY32inRect32 ( 
P_RECT32 pRect, //In 
P_XY32 pXY // In 
); 

Rect32Empty 

Test if a RECT32 has a width or height that is zero. 
Returns BOOLEAN. 

function Prototype BOOLEAN EXPORTED Rect32Empty ( 
P_RECT32 pRect // In 
); 

Comments Also, if pRect is pNull then this function returns true. 

Recti 6Empty 

Test if a RECTI 6 has a width or height that is zero. 
Returns BOOLEAN. 

Function Prototype BOOLEAN EXPORTED Recti 6Empty ( 
P_RECT16 pRect //In 
■); 

Comments Also, if pRect is pNull then this function returns true. 

MatCreate 

Create a MAT given a translate, rotate, and scale. 

Returns nothing. 

Function Prototype void. ' EXPORTED MatCreate ( 

P_MAT pMat, // Out 

COORD32 tX, // In 

COORD32 tY, // In 

ANGLE angle, //In 

FIXED sX, // In 

FIXED sY // In 
); 

Comments pMat is set to identity. Then the three transformation are post-multiplied in the order (1) translate, (2) 

rotate, and (3) scale. 

Matldentity 

Set a MAT to the identity matrix. 

Returns nothing. 

Function Prototype void EXPORTED Matldentity ( 
P_MAT //. Out 
); 
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MatRotate 

Rotate a MAT. 
Returns nothing. 



Function Pro' 



totype void EXPORTED MatRotate ( 
GEO_MAT_MULT order, 
P_MAT pMat, 

ANGLE angle 

); 



// In: {geoPreMultiply,geoPostMultiply} 

// In-Out: 

// In: 0-359 degrees 



iype 



MatTranslate 

Translate a MAT. 
Returns nothing. 

void EXPORTED MatTranslate ( 

GEO_MAT_MULT order, // In: {geoPreMultiply,geoPostMultiply} 

P_MAT pMat, // In-Out: 

P_XY32 xy //In: 

); 



MatScale 

Scale a MAT. 
Returns nothing. 



void EXPORTED MatScale ( 
GEO_MAT_MULT order, 
P_MAT pMat, 

P_SCALE scale 

); 



// In: {geoPreMultiply, geoPostMultiply} 
// In-Out: 
// In: 



Matlnvert 

Invert a MAT. 
Returns nothing. 

void EXPORTED Matlnvert ( 

P_MAT pDest, // Out: 

P_MAT pSource // In: 

); 

pSource is inverted and placed in pDest. pSource and pDest can be the same matrix. 



IFuocfior 



MatMultiply 

Multiply two MAT's. 
Returns nothing. 

void EXPORTED MatMultiply ( 

GEO_MAT_MULT order, 

P_MAT 

P_MAT 

P_MAT right 

); 



// In: {geoPreMultiply, geoPostMultiply} 



answer, // Out 
left, //In 

// In 



comments 



If order is geoPreMultiply, then answer = right * left. If order is geoPostMultiply, then answer = left 
right; 
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MatXYTransforml 6 

Transform a XY32 producing a XY16 result. 

Returns nothing. 

mttmn Prototype void EXPORTED MatXYTransforml 6 ( 
P_MAT pMat, //In 

P_XY32 pSource, //In 
P_XY16 pDest // Out 

); 

smments Each 32-bit number is rounded to 16-bits using Coord32Tol6. 



MatXYTransform32 

Transform a XY32 producing a XY32 result. 
Returns nothing. 

void EXPORTED MatXYTransform32 ( 

P_MAT pMat, //In 

P_XY32 pSource, //In 

P_XY32 pDest // Out 

); 

MatWHTransform 1 6 

Transform a SIZE32 producing a SIZE 16 result. 
Returns nothing. 

Function Prototype void EXPORTED MatWHTransforml6 ( 
P_MAT pMat, //In 

P_SIZE32 pSource, // In 
P_SIZE16 pDest // Out 

); 

Comments This transformation is similar to MatXYTransforml 6 except the translation components of the matrix 

are ignored and the values returned are always positive. 

Each 32-bit number is rounded to 16-bits using Coord32Tol6. 

MatWHTram^^^ 

Transform a SIZE32 producing a SIZE32 result. 

Returns nothing. 

Function Prototype void EXPORTED MatWHTransform32 ( 
P_MAT pMat, //In 

P_SIZE32 pSource, // In 
P_SIZE32 pDest // Out 

); 

Comments This transformation is similar to MatXYTransform32 except the translation components of the matrix 

are ignored and the values returned are always positive. 
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MatTransformRECT32 



Transform a RECT32. | 

a. 
Returns nothing. £ 

o 

?pe void EXPORTED MatTransformRECT32 ( Jj 

P_MAT pMat, //In $ 

P_RECT32 pSource // In-Out § 

); z 



Debugging Functions 



MatDump 

Prints the fields of a matrix. 
Returns nothing. 

function Prototype void EXPORTED MatDump (P_MAT pm) ; 

Comments This function may not work unless the debugging version ofwin.dll is being used. 

DumpRect 

Prints the fields of a rectangle. 
Returns nothing. 

Fyncflnn Prototype void EXPORTED DumpRect (P_RECT32 pRect) ; 

Comments This function may not work unless the debugging version ofwin.dll is being used. 

^Special Functions 

WARNING: The functions in this section (MatXTransforml6, MatYTransforml6, 
MatWTransforml6, and MatHTransforml6) work only in a limited set of cases: NO translation, NO 
rotation, and they perform NO rounding and thus can overflow the 16 bit result. 

These functions should not normally be used by application software. 

Ion Prototype C00RD16 EXPORTED MatXTransforml6 (P_MAT pi, C00RD16 x) 

C00RD16 EXPORTED MatYTransforml6 (P_MAT pi, C00RD16 y) 

C00RD16 EXPORTED MatWTransforml6 (P_MAT pi, C00RD16 w) 

C00RD16 EXPORTED MatHTransforml6 (P MAT pi, C00RD16 h) 



$i 
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PICSEG.H 



This file contains the API definition for clsPicSeg (Picture Segments). 

clsPicSeg inherits from clsSysDrwCtx. 

clsPicSeg provides a database and storage for drawing primitives. 

A Picture Segment creates a display list from the stream of messages defined by drawing context. The 
graphic elements in a PicSeg are called grafics. The display list can repaint to the same window or store 
the grafics and later repaint it to another window. It also provides a move/copy transfer type for grafics. 

The Picture Segment stores the following shapes as defined by clsSysDrwCtx: rectangle, ellipse, Bezier, 
polyline, polygon, sector rays, arc rays, chord rays, text. In addition, it defines a spline, and object types 
as an enhancement to the drawing context. It doesn't store images or raster operations such as CopyRect 
and XOR. Raster operations like XOR, AND, dynamic and fast modes defined by the drawing context 
apply to the whole display list. Similarly, transformations scale, translate, rotate and units apply to the 
PicSeg before drawing the list. The PicSeg stores the grafics in Logical Unit Coordinates as defined by 
the drawing context. 

PicSeg's provide display query messages allowing changes to grafic shapes it stores. The grafics in a 
picture segment are ordered; it keeps track of the current grafic. You can retrieve, alter, reorder, and 
delete individual grafics. 

Common uses of PicSeg's: 

PicSeg's generally used as the Data Object of a View (els View). A drawing View (like clsGrafPaper) 
translates the input strokes into grafics and draws them to the PicSeg, treating the PicSeg just like a 
Drawing Context. When the View gets msgWinRepaint it sends msgPicSegPaint to the PicSeg. 

The PicSeg's file data as an Object so they can be used as resources. A Drawing View could file many 
PicSegs with different resource ids to the same file. Latter a display View could look up the different 
PicSegs in the resource file and display them. 

PicSeg's are used to Move/Copy grafic data between Views. The transfer (xfer) mechanism uses an 
intermedate global PicSeg for grafics. 

#ifndef PICSEG_INCLUDED 
#define PICSEG_INCLUDED 
#ifndef SYSGRAF_INCLUDED 
#include <sysgraf .h> 
#endif 



Common #defines and typedefs 



Data Collection and Drawing Modes 

The PicSeg flags deterimine what to do with a draw messages. By default a message like 
msgDcDrawRectangle causes the PicSeg to store the rectangle in the display list and draw it on the 
window set by msgDcSetWindow. The following flags can prevent one or both of these thing from 
happening (picseg. flags). 
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tdefine picSegAdd 
tdefine picSegDraw 
♦define picSegSendDestroy 



flagO // on if PicSeg should add grafics. 

flagl // on if PicSeg should draw grafics 

flag2 // on Ob jectCall (msgDestroy, ...) 

// to an object grafic when it is 
// deleted from the PicSeg or if the 
// PicSeg is freed. 

The first grafic in the display list is 0. The last can be set by using msgPicSegSetCurrent with 

picSegTopGrafic or asking for the current number of grafics and then setting the current grafic. 

tdefine picSegTopGrafic 0x7FFFFFFF // theoretical maximum number of grafics 



OpCodes 



Each grafic in the PicSeg is given an OpCode that idenifies what type of data is stored in the pData 
member of PIC_SEG_GRAFIC. 

typedef U16 

typedef P_U16 

#define opCodeMasklnvisible 

#define opCodePolyline 
tdefine opCodeRectangle 
tdefine opCodeEllipse 
tdefine opCodePolygon 
tdefine opCodeSpline 
tdefine opCodeArcRays 
tdefine opCodeSectorRays 
tdefine opCodeChordRays 
tdefine opCodeText 
tdefine opCodeObject 

The basic grafic used with msgPicSegGetGrafic. The pData allocated in the a heap and must be freed 
by creator of the PicSeg. 



0P_C0DE; 




P_OP_CODE; 




0x1000 






// grafic.pData 


100 


// PIC_SEG_POLYLINE 


101 


// PIC_SEG_RECT 


102 


// PIC_SEG_ELLIPSE 


103 


// PIC_SEG_POLYGON 


104 


// PIC_SEG SPLINE 


105 


// PIC_SEG_ARC_RAYS 


106 


// PIC_SEG_ARC_RAYS 


107 


// PIC_SEG_ARC_RAYS 


55 


// PIC_SEG_TEXT 


150 


// PIC SEG OBJECT 



typedef struct { 

OP_CODE opcode; 

PJJNKNOWN pData; 

}PIC SEG GRAFIC, * P PIC SEG GRAFIC; 



// the type of grafic stored in pData 
// pointer to the grafic data 



Every grafic provides the basic painting attributes. 



typedef struct { 
SYSDC_PATTERN 

SYSDC_RGB 

U16 



linePat, 
fillPat; 
foregroundRGB, 
backgroundRGB ; 
lineThickness; 



// the line pattern 
// the fill pattern 
// the foreground color 
// the background color 
// the line width 



} PIC_SEG_PAINT, * P_PIC_SEG_PAINT; 

The polyline, polygon, and spline grafics provide line attributes. 

typedef struct { 

U8 join; 

U8 cap; 

U8 miterLimit; 

U8 spare; 
} PIC_SEG_PLINE_TYPE, * P_PIC_SEG_PLINE_TYPE; 

Text style attributes. 



typedef struct PIC_SEG_FONT_STYLE{ 






U16 alignChr 


3, 


// see sysDcAlignChr??? 


underline 


2, 


// 0, 1, 2 


strikeout 


2, 


// 0, 1 


spare 


9; 


// spare - default 



} PIC SEG FONT STYLE, P PIC SEG FONT STYLE; 
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Common #defines and typedefs 



The grafic.pData provided with grafic.opCode == opCodeText. 



PIC_SEG_ 


PAINT 


paint; 




RECT32 " 




rectangle; 




SYSDC_FONT_SPEC 


f ont Spec- 


// unique font 


PIC_SEG_ 


_FONT_STYLE 


sty le; 




SIZE16 " 




size; 


// size of text 


XY32 




cp; 


// text position 


U16 




length; 


// length of text 


U8 




textfl]; 


// null terminated text 



typedef struct PIC_SEG_TEXT{ £ 

I 
a. 
< 

O 
08 
«/) 

o 

o 

z 
// null terminated text 
} PIC_SEG_TEXT, * P_PIC_SEG_TEXT; 

The grafic.pData provided with grafic.opCode == opCodeEUipse. 

typedef struct { 

P IC_SEG_PAINT paint ; 

RECT32 ellipse; 

} PIC_SEG_ELLIPSE, * P_PIC_SEG_ELLIPSE; 

The grafic.pData provided with grafic.opCode == opCodeRectangle. 



typedef struct { 




PIC_SEG_PAINT 


paint ; 


RECT32 


rectangle; 


S16 


radius; 



// The rectangle radius 
// for square corners. 
} PIC_SEG_RECT, * P_PIC_SEG_RECT; 

The grafic.pData provided with grafic.opCode == opCodePolyline. The pData is of variable size 
depending on the number of points (pData->count). For Example, the third point is pData->points[3]. 
The size of pData is: (sizeof(PIC_SEG_POLYLINE) + sizeof(XY32) * ((pData->count)-l)). 

typedef struct { 

P IC_SEG_PAINT paint ; 

PIC_SEG_PLINE_TYPE type; 

U16 count; // number of points 

XY32 points [1] ; // variable number of points 

} PIC_SEG_POLYLINE, * P_PIC_SEG_POLYLINE; 

The grafic.pData provided with grafic.opCode == opCodePolygon. The pData is of varible size 
depending on the number of points (pData->count). For Example, the third point is pData->points[3]. 
The size of pData is: (sizeof(PIC_SEG_POLYGON) + sizeof(XY32) * ((pData->count)-l)). 

typedef struct { 

PIC_SEG_PAINT paint; 

PIC_SEG_PLINE_TYPE type; 

U16 count; // number of points 

XY32 points [1] ; // variable number of points 

} PIC_SEG_POLYGON, * P_PIC_SEG_POLYGON; 

The grafic.pData provided with grafic.opCode == opCodeSpline. A spline is a continuous number of 
four point Bezier curves. The first Bezier is defined by the first four points in pData->points. The 
second Bezier starts at pData->points[3]. The count minus one is a multiple of three. 
msgDcDrawBezier stores as a spline. The pData is of varible size depending on the number of points 
(pData->count). For Example, the third point is pData->points[3]. The size of pData is: 
(sizeof(PIC_SEG_SPLINE) + sizeof(XY32) * ((pData->count)-l)). 



typedef 


struct { 








PIC_ 


SEG 


_PAINT 




paint; 




PIC 


"seg" 


j>LINE_ 


_TYPE 


type; 




U16 








count ; 




XY32 








points 


[1]; 



// number of points 
// variable number of points 
} PIC SEG SPLINE, * P PIC SEG SPLINE; 
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The grafic.pData provided with grafic.opCode == opCodeArcRays, opCodeChordRays, or 
opCodeSectorRays. 



typedef struct { 






PIC_SEG_PAINT 


paint; 




RECT32 


bounds ; 




XY32 


rays [2] ; 




} PIC_SEG_ARC_RAYS, * P 


PIC_SEG_ARC_RAYS ; 




The grafic.pData provided with grafic.opCode == 


opCodeObject. 


typedef struct { 






PIC_SEG_PAINT 


paint; 




RECT32 


rectangle; 




OBJECT 


object; 




} PIC_SEG_OBJECT, * P_PIC_SEG_OBJECT; 




tdefine maxPolylineSize 


((OxFFFF / sizeof (XY32)) - sizeof (PIC_SEG_POLYLIN] 


typedef struct PIC SEG 


METRICS { 




U16 


flags; 




MESSAGE 


units; 


// information only 


S32 


numberGrafics; 


// information only 


S32 


currentGrafic; 


// information only 


SYSDC_PATTERN 


fillPat; 


// attributes of the next 


SYSDC_PATTERN 


linePat; 


// drawn grafic 


SYSDC_RGB 


foregroundRGB; 




SYSDC_RGB 


backgroundRGB ; 




SYSDC_LINE 


line; 




SYSDC_PATTERN 


clearFillPat; 


// clear 


SYSDC_PATTERN 


clearLinePat; 




SYSDC_RGB 


clearForegroundRGB; 




SYSDC_RGB 


clearBackgroundRGB; 




SYSDC_FONT_SPEC 


fontSpec; 


// font stuff 


SIZE16 


fontSize; 




PIC SEG FONT STYLE 


font Style; 




S32 


reserved [5] ; 




S32 


spare [8] ; 


// reserved 


} PIC_SEG_NEW_ONLY, PIC 


_SEG_METRICS, 




*P PIC SEG NEW_ONLY, 


*P PIC SEG METRICS; 





Messages 



Comments 



msgDump 

Dumps a PicSeg. Debug version only! 

Takes S32, returns STATUS. Category: class message. 

pArgs == everything and dc. pArgs == 1 PicSeg and metrics and does not Dump ancestor. pArgs == 2 
PicSeg metrics only and does not Dump ancestor. pArgs ==3 PicSeg database only and does not Dump 



ancestor. 



msgNew 

Creates a new PicSeg. 

Takes P_PIC_SEG_NEW, returns STATUS. Category: class message. 



tdefine picSegNewFields \ 

sysdcNewFields \ 

PIC SEG NEW ONLY picSeg; 
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Messages 

typedef struct PIC_SEG_NEW { 

picSegNewFields 

} PIC_SEG_NEW, *P_PIC_SEG_NEW; 3 

X 
a. 
< 

msgNewDefaults o 

Initializes a PIC_SEG_NEW structure to default values. w> 

Takes P_PIC_SEG_NEW, returns STATUS. Category: class message. § 



Message typedef struct PIC_SEG_NEW { 

ifgyments picSegNewFields 

} PIC_SEG_NEW, *P_PIC_SEG_NEW; 

omments Defaults: 



£ 



picSeg. flags = picSegDraw | picSegAdd | picSegSendDestroy 

picSeg. units = msgDcUnitsPoints 

picSeg.currentGrafic = -1 

picSeg. fillPat = sysDcPatBackground 

picSeg. linePat = sysDcPatForeground 

picSeg. backgroundRGB. all = SysDcGrayRGB(255) 

picSeg. f oregroundRGB . all = SysDcGrayRGB(O) 

picSeg. line. cap = 
picSeg. line. join = 
picSeg. line. miterLimit = 10 
picSeg. line. radius = 
picSeg. line. thickness = 1 

picSeg. clearFillPat = sysDcPatNil 

picSeg. clearLinePat = sysDcPatNil 

picSeg. clearForegroundRGB = SysDcGrayRGB(255) 

picSeg. clearBackgroundRGB = SysDcGrayRGB(O) 

picSeg. font Spec. id = Nil 

picSeg. font Spec. attr. group = sysDcGroupDefault 

picSeg. fontSpec.attr. weight = sysDcWeightNormal 

picSeg. fontSpec. attr. aspect = sysDcAspectNormal 

picSeg. fontSpec.attr. italic = false 

picSeg. fontSpec. attr. monospaced = false 

picSeg. fontSpec. attr. encoding = sysDcEncodeHWX850 

picSeg. fontSize.w = 1 

picSeg. fontSize.h = 1 

picSeg. f ontStyle . alignChr = 

picSeg. fontStyle. underline = sysDcAlignChrBaseline 

picSeg. f ontStyle. strikeout = 

picSeg. fontStyle. spare = 



msgRestore 

Restores the PicSeg metrics and grafics and sets the DC state. 

Takes P_OBJ_RESTORE, returns STATUS. Category: class message. 

Comments The Restore doesn't connect the PicSeg to a window. Before using the PicSeg it must be set to a window 

with msgDcSetWindow. 
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msgSave 

Saves the PicSeg metrics and grafics and the DC units and LUC matrix. 
Takes P_OBJ_SAVE, returns STATUS. Category: class message. 
utttetits The Save doesn't save the window connected to the PicSeg. 

Drawing Messages 

Messages of clsSysDrwCtx used by clsPicSeg: All of the following messages draw the shape and add it as 
a graflc to end of the of the PicSeg display list, provided the add and draw flags are turned on. 

msgDcDrawEllipse, msgDcDrawRectangle, msgDcDrawPolyline, msgDcDrawPolygon, 
msgDcDrawSectorRays, msgDcDrawArcRays, msgDcDrawChordRays, msgDcDrawBezier, 
msgDcDrawText 

PicSeg text defaults: spaceChar, spaceExtra, otherExtra 

All of the following messages change the DC and also the PicSeg state. PicSeg converts the x,y font scale 
to 16 bits dc units. 

msgDcSetForegroundRGB, msgDcSetBackgroundRGB, msgDcSetLinePat, msgDcSetFillPat, 
msgDcSetLine, msgDcSetLineThickness, msgDcOpenFont msgDcScaleFont, msgDcIdentityFont, 
msgDcUnits... 

msgPicSegPaint 

Paints the grafics in the PicSeg. 
Takes pNull, returns STATUS. 

tdefine msgPicSegPaint MakeMsg(clsPicSeg, 7) 

«menfs Object Call either msgWinBeginPaint or msgWInBeginRepaint before using this message. 



msgPicSegDrawSpline 

Adds and draws the grafic to the end of the display list. 

Takes P_PIC_SEG_SPLINE, returns STATUS. 

tdefine msgPicSegDrawSpline MakeMsg(clsPicSeg, 104) 

Message typedef struct { 

Arguments PIC_SEG_PAINT paint; 

P IC_SEG_PLINE_TYPE type ; 

U16 count; // number of points 

XY32 points [1]; // variable number of points 

} PIC_SEG_SPLINE, * P_PIC_SEG_SPLINE; 

msgPicSegDrawObject 

Adds and draws an object to the PicSeg display list. 

Takes P_PIC_SEG_OBJECT, returns STATUS. 

tdefine msgPicSegDrawObject MakeMsg(clsPicSeg, 121) 

ffessoge typedef struct { 

Arguments PIC_SEG_PAINT paint; 

RECT32 rectangle; 

OBJECT object; 

} PIC SEG OBJECT, * P PIC SEG OBJECT; 
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msgPicSegPaintObject 

«/> 

Sent by the PicSeg to objects in its database so they can draw themselves. ^ 

a 

Takes P_PIC_SEG_PAINT_OBJECT, returns STATUS. 2 

O 

tdefine msgPicSegPaintObject MakeMsg(clsPicSeg, 46) °8 

typedef struct { O 

PIC_SEG_PAINT paint; | 

RECT32 rectangle; 5 

OBJECT object; 

OBJECT picSeg; 

S32 reserved [6]; 

} PIC SEG PAINT OBJECT, * P PIC SEG PAINT OBJECT; 



msgPicSegDrawGrafic 

Draws a grafic from the PicSeg. 

Takes P_PIC_SEG_GRAFIC, returns STATUS. 

tdefine msgPicSegDrawGrafic MakeMsg(clsPicSeg, 10) 

typedef struct { 

OP_CODE opCode; // the type of grafic stored in pData 

P_UNKNOWN pData; // pointer to the grafic data 

}PIC_SEG_GRAFIC, * P_PIC_SEG_GRAFIC; 

The grafic opCode must be set to one of the opCode's defined by PicSeg's. Can be used for HitTest on a 
specific grafic. Never adds the grafic to the PicSeg. Responds to flags picSegDraw. 

msgPicSegDrawGraficIndex 

Sets the current grafic to index and draws it. 

Takes S32 index, returns STATUS. 

tdefine msgPicSegDrawGraficIndex MakeMsg(clsPicSeg, 11) 

Can be used for HitTest on a specific grafic. 

msgPicSegDrawGraficList 

Draws all the grafics indexed by the list. 

Takes P_PIC_SEG_LIST, returns STATUS. 

tdefine msgPicSegDrawGraficList MakeMsg(clsPicSeg, 8) 

typedef struct { 

S32 count; // number of grafic in list to draw 

P_S32 plndex; // pointer to the list of grafics 

}PIC SEG LIST, * P PIC SEG LIST; 



msgPicSegAddGrafic 

Adds a grafic to the PicSeg and Draws the grafic. 

Takes P_PIC_SEG_GRAFIC, returns STATUS. 

tdefine msgPicSegAddGrafic MakeMsg(clsPicSeg, 9) 

fesscige typedef struct { 

irsuments OP_CODE opCode; // the type of grafic stored in pData 

P_UNKN0WN pData; // pointer to the grafic data 

}PIC SEG GRAFIC, * P PIC SEG GRAFIC; 
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Comments The grafic opCode must be set to one of the opCode's defined by PicSeg's. Responds to flags picSegAdd 

and picSegDraw. 

msgPicSegGetMetrics 

Passes back the metrics of the PicSeg. 

Takes P_PIC_SEG_METRICS, returns STATUS. 

tdefine msgPicSegGetMetrics MakeMsg(clsPicSeg, 3) 

msgPicSegSetMetrics 

Sets the metrics of the PicSeg. 
Takes P_PIC_SEG_METRICS, returns STATUS. 

tdefine msgPicSegSetMetrics MakeMsg(clsPicSeg, 4) 

emments You cannot set picseg.numberGrafics. 

msgPicSegSetFlags 

Sets the PicSeg flags. 

Takes S32, returns STATUS. 

#define msgPicSegSetFlags MakeMsg(clsPicSeg, 5) 

msgPicSegGetFlags 

Gets the PicSeg flags. 

Takes P_S32, returns STATUS. 

#define msgPicSegGetFlags MakeMsg(clsPicSeg, 6) 

Hit Test 

msgPicSegHitTest 

Performs a hit test on the PicSeg, passing back a single grafic index. 

Takes P_PIC_SEG_HIT_LIST, returns STATUS. 

tdefine msgPicSegHitTest MakeMsg(clsPicSeg, 23) 

Arguments typedef struct { 

RECT32 rect; // rectangle for the hit test 

S32 index; // in start grafic - out end grafic 

} PIC_SEG_HIT_LIST, * P_PIC_SEG_HIT_LIST; 

Comments index - in: First grafic to start hit test hit stops at grafic 0. Use picSegTopGrafic for starting at the 

top most grafic. out: The grafic hit if status is stsDcHitOn or stsDcHitln. Otherwise 0. 

STATUS return: 

StsDcHitOn if the line intersects the hit rectangle 

stsDcHitln if the rectangle is inside a closed figure 

stsDcHitOut if there was no hit 

msgWinBeginPaint must be sent to the window first. msgWinEndPaint must be sent to the 
window after. 
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Editing the PicSeg Display List 



msgPicSegErase 5 

Deletes all grafics. ® 



msgPicSegRemove 

Deletes a grafic, takes a grafic Index. Does not send msgDestroy to objects in the PicSeg. 

Takes S32, returns STATUS. 

#define msgPicSegRemove MakeMsg(clsPicSeg, 45) 

msgPicSegDelta 

Changes the current grafic. 

Takes P_PIC_SEG_GRAFIC, returns STATUS. 

Idefine msgPicSegDelta MakeMsg(clsPicSeg, 27) 

Message typedef struct { 

Irgwments OP_CODE opCode; // the type of grafic stored in pData 

P_UNKNOWN pData; // pointer to the grafic data 

}PIC_SEG_GRAFIC, * P_PIC_SEG_GRAFIC; 

msgPicSegGetGrafic 

Gets the current grafic. 

Takes P_PIC_SEG_GRAFIC, returns STATUS. 

#define msgPicSegGetGrafic MakeMsg(clsPicSeg, 28) 

tessoge typedef struct { 

Arguments OP_CODE opCode; // the type of grafic stored in pData 

P_UNKNOWN pData; // pointer to the grafic data 

}PIC_SEG_GRAFIC, * P_PIC_SEG_GRAFIC; 

Comments Data must be freed by caller. 



msgPicSegSetCurrent 

Sets the current grafic index. 
Takes S32, returns STATUS. 

tdefine msgPicSegSetCurrent MakeMsg(clsPicSeg, 30) 

Comments Specifying picSegTopGrafic sets the current grafic to the last grafic in the list. 



u> 



Takes nothing, returns STATUS. £ 

O 
#define msgPicSegErase MakeMsg(clsPicSeg, 24) ^ 

msgPicSegDelete 

Deletes a grafic, takes a grafic Index. Sends msgDestroy to objects in the PicSeg. 

Takes S32, returns STATUS. 

tdefine msgPicSegDelete MakeMsg(clsPicSeg, 26) 
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msgPicSegGetCurrent 

Gets the index of the current grafic. 
Takes P_S32, returns STATUS. 
#define msgPicSegGetCurrent 



MakeMsg(clsPicSeg, 31) 



msgPicSegGetCount 

Gets the number of grafics in the PicSeg. 
Takes P_S32, returns STATUS. 
#define msgPicSegGetCount 



MakeMsg(clsPicSeg, 32) 



Comments 



msgPicSegMakelnvisible 

Makes the given grafic invisible. 

Takes S32, returns STATUS. 

♦define msgPicSegMakelnvisible MakeMsg(clsPicSeg, 33) 

Changes the graflcs opCode by oring in opCodeMasklnvisible. 



Comments 



msgPicSegMake Visible 

Makes the given grafic visible. 

Takes S32, returns STATUS. 

#define msgPicSegMakeVisible MakeMsg(clsPicSeg, 34) 

Changes the grafics opCode by masking out opCodeMasklnvisible. 



msgPicSegChangeOrder 

Changes the order of the grafics in the display, Moving the current grafic to the given index. 

Takes S32, returns STATUS. 

♦define msgPicSegChangeOrder MakeMsg(clsPicSeg, 35) 

If the given index is less than the current index, then the grafics in between shift forward. 

If the given index is greater than the current index, then the grafics in between shift backward. 

msgPicSegSizeof 

Returns the size of the (PIC_SEG_GRAFIC).pData in bytes. 
Takes P_PIC_SEG_GRAFIC, returns S32. 



♦define msgPicSegSizeof 

Message typedef struct { 
Arguments OP CODE opCode; 

PJJNKNOWN pData; 
}PIC SEG GRAFIC, * P PIC SEG GRAFIC; 



MakeMsg(clsPicSeg, 39) 

// the type of grafic stored in pData 
// pointer to the grafic data 
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Messages Used For Move Copy 



You can move and copy grafics in picture segments using the selection manager XFER mechanism type 
xferPicSegObject. The PicSeg is a data object and only helps define the method. The PicSeg itself does 
not have the selection. Usually the View, using the PicSeg as its data object, responds to move and copy O 



4 



messages. The selected View puts xferPicSegObject on the list when it receives msgXferList. With a M 

match the receiving View creates a global heap PicSeg and sets up the XFER_OBJECT: o 

o 

z 



XFER_OBJECT 


xferObject; 


OBJECT 


picSeg; 


MAT 


matrix; 



memset (SxferObject, 0, sizeof (XFER_OBJECT) ) ; 
xf erOb ject . id = xferPicSegObject; 
xferObject. receiver = self; 

StsJmp(ObjectSendUpdate(msgXferGet, sel, fcxferObject, \ 
(U32) sizeof (XFER_OBJECT) ) , sts, error); 

xferPicSeg = xferObject.uid; 

Ob jectCall (msgDcSetWindow, xferPicSeg, (P_ARGS)self) ; 

ObjectCall(msgPicSegScaleUnits, xferPicSeg, (P_ARGS)psMetrics. units) ; 

matrix. m31 = pTip->x - bounds. origin. x; 

matrix. m32 = pTip->y - bounds. origin. y; 

Matldentity (matrix) ; 

Ob jectCall (msgPicSegTransf orm, xferPicSeg, &matrix) ; 

Ob jectCall (msgPicSegCopy, picSeg, (P_ARGS) xferPicSeg) ; 

Ob jectCall (msgDestroy, xferPicSeg, pNull); 

The receiving View then ObjectSends msgXferGet to the selection. The selected View takes 
msgXferGet sets the xfer PicSeg's metrics to its own and puts the selected grafics into the global PicSeg. 
The receiving View must rebind the xfer PicSeg to a window using msgDcSetWindow. Then transform 
the xfer PicSeg with msgPicSegScaleUnits and msgPicSegTransform. The xferPicSeg is copied into the 
receiving View's PicSeg with msgPicSegCopy. The global PicSeg is then freed by the receiving View. 

#define tagPicSeg MakeTag(clsPicSeg,0) 

msgPicSegScaleUnits 

Scales all coordinates in the PicSeg from the old units to the new units, then sets the units of the PicSeg 
to the new units. 

Takes MESSAGE, returns STATUS. 

#define msgPicSegScaleUnits MakeMsg(clsPicSeg, 36) 

Valid arguments: msgDcUnitsMetric, msgDcUnitsMil, msgDcUnitsPoints, msgDcUnitsTwips, 
msgDcUnitsPen, msgDcUnitsPen, msgDcUnitsDevice, msgDcUnitsLayout. 

Invalid arguments: msgDcUnitsWorld. 



msgPicSegTransform 

Transforms all coordinates in the PicSeg database with the provided matrix. 

Takes MAT, returns STATUS. 

#define msgPicSegTransform MakeMsg(clsPicSeg, 37) 

Comments Doesn't change line thickness, text size and rect radius. Thus this message is best used for Rotation and 

Translation only. 
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msgPicSegCopy 

Copies the contents of the specified PicSeg to self. 

Takes OBJECT, returns STATUS. 

tdefine msgPicSegCopy MakeMsg(clsPicSeg, 38) 

Takes no account for units, scale, rotate and translate differences. 
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SYSFONT.H 



This file provides font related definitions used by sysgraf.h. 

Overview 

This file defines the values you give Sysgraf if you want to set the font parameters. See sysgraf.h, starting 
with msgSysDcFontld. 

tifndef SYSFONT_INCLUDED 
#define SYSFONT INCLUDED 



Font Attributes 



tdefine 


sysDcGroupDefault 


// e 


tdefine 


sysDcGroupUserlnput 


1 


tdefine 


sysDcGroup Venetian 


2 


#define 


sysDcGroupOldStyle 


3 


#define 


sysDcGroupTransitional 


4 


#define 


sysDcGroupModernRoman 


5 


#define 


sysDcGroupEgyptian 


6 


tdefine 


sysDcGroupSansSerif 


7 


tdefine 


sysDcGroupDisplayRoman 


8 


tdefine 


sysDcGroupScript 


9 


tdefine 


sysDcGroupGraphic 


10 


tdefine 


sysDcGroupTypewriter 


11 


tdefine 


sysDcSoftwareDefined 


15 // i 


tdefine 


sysDcWeightLight 





tdefine 


sysDcWeightNormal 


1 


tdefine 


sysDcWeightBold 


2 


tdefine 


sysDcWeightExtraBold 


3 


tdefine 


sysDcAspectCondensed 





tdefine 


sysDcAspectNormal 


1 


tdefine 


sysDcAspectExtended 


2 


tdefine 


sysDcEncodeLinear 





tdefine 


sysDcEncodeAdobeStandard 


1 


tdefine 


sysDcEncodeAdobeSymbol 


2 // 


tdefine 


sysDcEncodeIBM850 


3 // 


tdefine 


sysDcEncodeGoSystem 


4 


tdefine 


sysDcEncodeHWX850 


5 


tdefine 


sysDcEncodeUnicode 


6 


tdefine 


sysDcAlignChrTop 





tdefine 


sysDcAlignChrCenter 


1 


tdefine 


sysDcAlignChrBaseline 


2 


tdefine 


sysDcAlignChrDescender 


3 



also "system" font 



subclass must draw glyphs 



not implemented 

MiniText and MiniNote expect this 
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Font Specification 



To open a font a SYSDC_FONT_SPEC is used. This is a 32 bit number which may be interesting to file as 
a compact representation of a particular font specification (family, styles, etc., size is another matter). 

It consists of two major fields, an "id", which is a 16-bit number that identifies a family, like Times 
Roman, or Futura. 

This number can be derived from a four-byte string like "TR55" using the function SysDcFontld 
(defined in sysgraf.h). However, it is better to query the system as to the list of currently available fonts. 
Support for this exists in tktable.h (see TkTableFillArrayWithFonts) and fontlbox.h (see 
clsFontListBox). 

The second field contains attributes like boldness, italic, etc. Also, it contains a field called group. The 
group is a redundant encoding of information in the id. If the id, which identifies a specific font or font 
family, is not available, the group is used to locate a font with similar characteristics. 

Another interesting field is encoding. This field serves to identify the "character set" of the bytes passed 
to msgDcDrawText. 

Thus, if you file this 32-bit number along with a string of text the following will hold true: 

1 The "interpretation" of the characters in the string is noted. 

2 The "font family" is noted 

3 If the "font family" is not available the next time the string is diplayed (perhaps on a different 

machine), then an acceptable substitute can be found. 



typedef 


struct 






U16 


group 


4, 


// use sysDcGroup . . . 




weight 


2, 


// use sysDcWeight . . . 




aspect 


2, 


// use sysDcAspect . . . 




italic 


1, 


// use TRUE for italic 




monospaced 


1, 


// use TRUE for monospaced 




encoding 


6; 


// use sysDcEncode . . . 


} SYSDC_ 


_FONT_ATTR, * I 


>_SYSDC_ 


_FONT_ATTR; 


typedef 


struct 







{ 



U16 id; 

SYSDC_FONT_ATTR attr; 
} SYSDC_FONT_SPEC, * P_SYSDC_FONT_SPEC; 
typedef struct 
{ 



// for now binds to "default" font 



SYSDC_FONT_SPEC 

CHAR 

C00RD16 



// actual 



// usually a small negative number 



// usually a small negative number 



spec; 

name [80] ; 

spaceWidth, 

underThickness, 

underPos, 

xPos, 

ascenderPos, 

descenderPos; 
SIZE16 em; 

COORD 16 maxY, 

minY; 
} SYSDC_FONT_METRICS, * P_SYSDC_FONT_METRICS; 
typedef struct 
{ 

C00RD16 widths[256]; // per spec. encoding 

} SYSDC FONT WIDTHS, * P SYSDC FONT WIDTHS; 
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typedef struct 
{ 

U16 alignChr; 

U16 underline; 

U16 strikeout; 

P_CHAR pText; 

U16 lenText; 

XY32 cp; 

COORD32 stop; 

U16 spaceChar; 

COORD 16 spaceExtra, 
otherExtra; 
} SYSDC_TEXT_OUTPUT, * P_ 

typedef struct 
{ 

XY16 min, 
max; 

C00RD16 width; 
} SYSDC_EXTENTS16, 
typedef struct 
{ 



// use sysDcAlignChr. . . 
// use 0,1, or 2 
// use or 1 

//in (and out for measure) 
//in and out, where to place string 
// used by msgDcMeasureText 
// code for space, usually 32 
// added to width of space 
// added to width of every char 
SYSDC TEXT OUTPUT; 



* P SYSDC EXTENTS16; 



P_SYSDC_EXTENTS16 
P_CHAR 
U16 
} SYSDC CHAR METRICS, 



pExtents; 
pText ; 
len; 
* P SYSDC CHAR METRICS; 
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SYSGRAF.H 



This file provides the API for clsSysDrwCtx. 

clsSysDrwCtx inherits from clsDrwCtx, an abstract class. 

Defines the fundamental drawing services. An instance of clsSysDrwCtx, often called a "DC", is an 
object that is used to draw onto windows. After a DC is created, it is bound to a window (see 
msgDcSetWindow). After this step, drawing messages sent to the DC will result in drawing onto the 
bound window. While a DC may remain bound to a window forever, such drawing messages are only 
effective inside an "update episode" bracketed by msgWinBeginRepaint and msgWinEndRepaint. 

There are a number of other DC messages that do not have to be sent inside an "update episode"; for 
instance msgDcLWCtoLUC_XY32. However, many of these messages implicitly require device or 
window metrics to produce the correct results. Thus, as a rule, a DC should be bound to a window 
before it is used. 

Terminology: 

DU4 ~ Device Units, 4th Quadrant. A 4th quadrant coordinate system; device space, device units. This 
is used internally, but not seen by application software. 

LWC ~ Logical Window Coordinates. A 1st quadrant coordinate system. The lower-left-hand corner of 
the window is 0,0. The units are device pixels. 

LUC ~ Logical Unit Coordinates. A 1st quadrant coordinate system provided by the DC. The default 
units can be a real-world measure like points or mils; and they can be translated, rotated and scaled. 

A number of font-related data structures are defined in sysfont.h. 

#ifndef SYSGRAF_INCLUDED 
#define SYSGRAF_INCLUDED 
#ifndef GO_INCLUDED 
♦include <go.h> 
tendif 

#ifndef CLSMGR_INCLUDED 
♦include <clsmgr.h> 
tendif 

#ifndef GEO_INCLUDED 
♦include <geo.h> 
♦endif 

♦ifndef WIN_INCLUDED 
♦include <win.h> 
#endif 

#ifndef SYSFONT_INCLUDED 
♦include <sysfont.h> 
#endif 
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Overview 



Sysgraf (aka clsSysDrawCtx aka ImagePoint) is the lowest level drawing interface PenPoint provides 
above the bit level. The division of labor here is that Windows worry about parceling out screen 
real-estate while Sysgraf worries about drawing on the screen. If you want to draw things in a window, 
you create a drawing context (an instance of clsSysDrawCtx), bind it to the window you want to draw 
in (by sending msgDcSetWindow to the drawing context), and send messages to the drawing context. 

If you plan to use a drawing context to render text, you should understand the use of 
msgDcMeasureText, which lets you determine how large a piece of text will be before you actually draw 
it. It is also important to know that although sysgraf allows you to set many different parameters, 
including font, rotation, line thickness, etc. you may only change these between drawing calls. That is, if 
you want to render plain text, a word in italics, and more plain text, you need to send three separate 
msgDcDrawText messages, changing to italics after the first one and back to normal after the second. 

If you plan to use sysGraf at all, it will be well worth your while to browse all the messages below. 
// Message numbers available: 7, 8, 9, 34, 35, 36, 37, 38; next up: 110 



msgNew 

Creates a system drawing context. 

Takes P_SYSDC_NEW, returns STATUS. Category: class message. 

typedef struct SYSDC_NEW_ONLY { 

U32 reserved; 

} SYSDC_NEW_ONLY, *P_SYSDC_NEW_ONLY; 

♦define sysdcNewFields \ 
objectNewFields \ 

SYSDC_NEW_ONLY sysDc; 

typedef struct 
{ 

sysdcNewFields 
} SYSDC NEW, * P SYSDC NEW; 



msgNewDefaults 

Initializes the SYSDCJNEW structure to default values. 

Takes P_SYSDC_NEW, returns STATUS. Category: class message. 

ssoge typedef struct 

foments { 

sysdcNewFields 
} SYSDC_NEW, * P_SYSDC_NEW; 
sysDc. reserved = 0; 



Binding to a Window 



msgDcSetWindow 

Binds a window to the receiver and returns the previously bound window. 

Takes WIN, returns WIN. 

♦define msgDcSetWindow msgDrwCtxSetWindow 



SYSGRAF.H 289 

Graphic State Control 



Comments All output through the DC will now appear on this window. A DC must be bound to a window before 

most messages will work. 



msgDcGetWindow 2 

Gets the window to which the drawing context is bound. * 

Takes pNull, returns WIN. O 

#define msgDcGetWindow msgDrwCtxGetWindow 5 



F Graphic State Control 



CO 



msgDcInitialize 

Sets graphics state to initial values. 

Takes pNull, returns stsOK. 

♦define msgDcInitialize MakeMsg(clsSysDrwCtx, 50) 

Comments The initial values are: 

units in (LUC) = msgDcUnitsPoints 

units out = msgDcUnitsDevice 

matrix = identity, 1st quadrant 

premultiply = FALSE 

clipping = none, except to window 

raster op = sysDcRopCopy 

drawing mode = sysDcDrawNormal I sysDcHoldDetail 

plane mask = see msgDcPlaneNormal 

line. cap = sysDcCapButt 

line. join = sysDcJoinMiter 

line. thickness = 1 unit (point) 

line.miterLimit = 10 

line. radius = 

foreground color = sysDcRGBBlack 

background color = sysDcRGBWhite 

fill pattern = sysDcPatBackground 

fill mode = even/odd (see sysDcWindingFill) 

line pattern = sysDcPatForeground 

logical font = default font, size is 1 unit (point) 

msgDcPush 

Gets the graphics state and stores it. 

Takes P_SYSDC_STATE, returns stsOK. 

#define msgDcPush MakeMsg(clsSysDrwCtx, 31) 

Arguments typedef struct 

{ 

U8 state [448], • 
} SYSDC_STATE, * P_SYSDC_STATE; 

Comments While the names msgDcPush/msgDcPop imply a stack-like use for these messages (as is their intended 

application); this is not a requirement. There is no stack internal to the DC. State is copied in and out of 
the argument buffer. 

One application is to pre-stage frequently needed combinations of state (fonts, colors, etc.) in an array of 
these buffers; and then pop them into a single DC as needed. This is more memory efficient than having 
several DCs, and nearly as fast. 
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SYSDC_STATE is an opaque data type. There is no value in examining the bytes therein. It can be stored 
temporarily; but, it should not be filed, as it may change from release to release of the software. 



msgDcPop 

Sets the graphics state from one saved by msgDcPush. 

Takes P_SYSDC_STATE, returns stsOK. 

#define msgDcPop MakeMsg(clsSysDrwCtx, 32) 

typedef struct 
{ 

U8 state [448]; 
} SYSDC_STATE, * P_SYSDC STATE; 

msgDcPushFont 

Gets the font state and stores it. 

Takes P_SYSDC_FONT_STATE, returns stsOK. 

♦define msgDcPushFont MakeMsg(clsSysDrwCtx, 51) 

typedef struct 
{ 

U8 state [256]; 
} SYSDC_FONT_STATE, * P_SYSDC_FONT_STATE; 

The same comments made under msgDcPush apply to msgDcPushFont. 

msgDcPopFont 

Sets the font state from one saved by msgDcPushFont. 

Takes P_SYSDC_FONT_STATE, returns stsOK. 

♦define msgDcPopFont MakeMsg(clsSysDrwCtx, 52) 

lessage typedef struct 

ifguments { 

U8 state [256]; 
} SYSDC FONT STATE, * P SYSDC FONT STATE; 



msgDcSetMode 

Sets the drawing mode and returns the old SYSDCJVfODE. 
Takes SYSDC_MODE, returns SYSDC_MODE. 

♦define msgDcSetMode MakeMsg(clsSysDrwCtx, 2) 



Enuml6(SYSDC_M0DE) 




t 

sysDcDrawNormal 


= 0, 


sysDcDrawFast 


= flagO, 


sysDcDrawDynamic 


= flagl, 


sysDcHoldDetail 


= flag2, 


sysDcWindingFill 


= flag3, 


sysDcHitTest 


= flag4, 


sysDcAccumulate 


= flag7, 


sysDcHoldLine 


= flag5, 


sysDcPreMultiply 


= flag6 



// draw faster with gross loss of fidelity 
// sets up XOR style drawing 
// keeps lines from vanishing 

// must set with msgDcHitTest 

// must set with msgDcAccumulateBounds 

// must set with msgDcHoldLine 

// can set with msgDcSetPreMultiply 
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msgDcGetMode 

Gets the drawing mode. j 

Takes pNull, returns SYSDC_MODE. £ 

o 

#define msgDcGetMode MakeMsg(clsSysDrwCtx, 65) °8 

msgDcSetPreMultiply | 

Sets the pre-multiply state and returns the old state. ^ 

Takes BOOLEAN, returns BOOLEAN. UL 

#define msgDcSetPreMultiply MakeMsg(clsSysDrwCtx, 96) 

Comments This affects the matrix arithmetic implicit in msgDcScale, msgDcRotate and msgDcTranslate. The 

default mode is post-multiply. The default for PostScript is pre-multiply; so when borrowing algorithms 
from PostScript sources this could be useful. 

msgDcSetRop 

Sets the raster op and returns the old rop. 

Takes SYSDC_ROP, returns SYSDC_ROP. 

tdefine msgDcSetRop MakeMsg(clsSysDrwCtx, 1) 

Argument s Enuml 6 ( SYSDC_ROP ) 

{ 
sysDcRopCOPY, 
sysDcRopAND, 
sysDcRopOR, 
sysDcRopXOR, 
sysDcRopNCOPY, 
sysDcRopNAND, 
sysDcRopNOR, 
sysDcRopNXOR 
}; 

Comments Note that there are not many good reasons to be using this message; the results are rather device 

dependent. If you need to draw with an XOR raster op, use msgDcSetMode to set the 
sysDcDrawDynamic flag instead. 



msgDcPlaneNormal 

Sets the plane mask to the normal plane(s), returning the old mask. 
Takes nothing, returns SYSDC_PLANE_MASK. 

tdefine msgDcPlaneNormal MakeMsg(clsSysDrwCtx, 41) 

typedef U16 SYSDC PLANE_MASK; 



msgDcPlanePen 

Sets the plane mask to the plane(s) for pen ink, returning the old mask. 
Takes nothing, returns SYSDC_PLANE_MASK. 

tdefine msgDcPlanePen MakeMsg(clsSysDrwCtx, 42) 

Comments In most situations it is better to use clsTrack to draw on the pen plane(s). See trackh. 
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Comments 



msgDcPlaneMask 

Sets an arbitrary plane mask, returning the old mask. 

Takes SYSDC_PLANE_MASK, returns SYSDC_PLANE_MASK. 

♦define msgDcPlaneMask MakeMsg(clsSysDrwCtx, 43) 

This interface is NOT RECOMMENDED for application software. It is inherently non-portable. 

msgDcGetLine 

Gets all line attributes if pArgs is P_SYSDC_LINE. Returns line thickness. 
Takes P_SYSDC_LINE, returns COORD16. 

♦define msgDcGetLine MakeMsg(clsSysDrwCtx, 62) 

If P_SYSDC_LINE is pNull then only line thickness is returned. 

msgDcSetLine 

Sets all line attributes. Returns old line thickness. 

Takes P_SYSDC_LINE, returns COORD16. 

tdefine msgDcSetLine MakeMsg(clsSysDrwCtx, 4) 



Comments 



Arguments 



Comments 



Enuml6(SYSDC CAP) 




{ sysDcCapSquare 


= o, 


sysDcCapButt 


= 1, 


sysDcCapRound 

}; 


= 2, 


Enuml6(SYSDC JOIN) 




{ sysDcJoinMiter 


= o, 


sysDcJoinBevel 


= 1, 


sysDcJoinRound 

}; 


= 2, 


typedef struct 




i 

SYSDC CAP 


cap; 


SYSDC JOIN 


join; 


C00RD16 


thickness; 


U16 


miterLimit; 


S16 


radius; 



// Choose + number, 10 recommended. 
// For rounded corner rectangles 
// use + number or sysDcRadiusAuto . 
// For square corner rectangles use 0. 
// This number is in LUC. 



} SYSDC_LINE, * P_SYSDC_LINE; 
tdefine sysDcRadiusAuto 



(-1) 



Both line thickness and the radius value for creating rounded corner rectangles are in LUC. 



Comments 



msgDcSetLineThickness 

Sets line thickness to new value; returns old line thickness. 

Takes COORD 16, returns COORD 16. 

tdefine msgDcSetLineThickness MakeMsg(clsSysDrwCtx, 79) 

This is the best message for quickly changing line thickness and restoring it back. 
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msgDcHoldLine 



(A 

Turns hold line thickness mode on/off; returns old hold mode. ^ 

Takes BOOLEAN, returns BOOLEAN. | 

o 

♦define msgDcHoldLine MakeMsg(clsSysDrwCtx, 63) «8 

«A 

Comments msgDcHoldLine (TRUE) causes the current line thickness to be made immune from the effects of 5 

scaling (msgDcScale, msgDcUnitsXXXX). msgDcHoldLine(FALSE) will cancel hold mode. z 

msgDcSetLine/Thickness messages will cause the line thickness to change, but having changed, it will 
still be immune from the effects of scaling until hold mode is canceled. 

The DC must be bound to a window when this message is sent. 

|F Device Independent Color 

#define sysDcRGBTransparent ((U32)0) 

♦define sysDcRGBBlack (SysDcGrayRGB(O) ) 

♦define sysDcRGBGray66 (SysDcGrayRGB(85) ) 

♦define sysDcRGBGray33 (SysDcGrayRGB(170) ) 

♦define sysDcRGBWhite (SysDcGrayRGB(255) ) 

typedef union 
{ 
U32 all; 
struct 
{ 
U8 red, 
green, 
blue, 

transparency; 
} rgb; 

} SYSDC_RGB, * P_SYSDC_RGB; 
♦define SysDcGrayRGB (v) MakeU32 (MakeU16 (v, v) ,MakeUl6(v,255) ) 

These messages set and get the foreground and background colors by RGB specification. The "set" 
messages take an RGB specification (cast to a U32) and return stsOK. 

The "get" messages store the current value into a U32 (or SYSDC_RGB) pointed to by pArgs. 

The structure SYSDCJRGB is a union of the four r-g-b-t fields and a U32. This allows RGB values to be 
compared easily as U32 values. The transparency byte should always be 255 for opaque color. It can be 
when setting the background color to transparent (in which case the red, green, blue values are not 
examined). Intermediate transparency values are not supported. 

The macro SysDcGrayRGB takes a value between 0..255 and returns a U32 with the r-g-b bytes set to 
the value, and the transparency byte set to 255. The value can be used for a pure transparent RGB. 

The set messages find the closest matching color to the RGB specification; they do not create new 
colors. To create new colors see msgDcMixRGB (which is not implemented yet). 

Unlike the palette oriented messages (msgDcSetForegroundColor, msgDcSetBackgroundColor) colors 
set using these RGB messages are portable across a variety of devices and are automatically retranslated 
when the DC is connected to a different device. 
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msgDcSetForegroundRGB 

Sets foreground color using an RGB specification. 
Takes U32, returns stsOK. 

tdefine msgDcSetForegroundRGB MakeMsg(clsSysDrwCtx, 75) 

Comments When using this interface, see the constants sysDcRGB... for the standard colors. 

msgDcSetBackgroundRGB 

Sets background color using an RGB specification. 
Takes U32, returns stsOK. 

#define msgDcSetBackgroundRGB MakeMsg(clsSysDrwCtx, 76) 

Comments When using this interface, see the constants sysDcRGB... for the standard colors. 



msgDcInvertColors 

Swaps foreground and background colors. 

Takes pNull, returns stsOK. 

tdefine msgDcInvertColors MakeMsg(clsSysDrwCtx, 64) 



msgDcGetForegroundRGB 

Returns foreground RGB value. 

Takes P_U32 or P_SYSDC_RGB, returns stsOK. 

tdefine msgDcGetForegroundRGB MakeMsg(clsSysDrwCtx, 77) 

msgDcGetBackgroundRGB 

Returns background RGB value. 

Takes P_U32 or P^SYSDC_RGB, returns stsOK. 

tdefine msgDcGetBackgroundRGB MakeMsg(clsSysDrwCtx, 78) 

Device Dependent Color 

typedef U16 SYSDC_COLOR; 

tdefine sysDdnkTransparent ( (SYSDC_COLOR) 0x8000) 

tdefine sysDcInkBlack ( (SYSDC_C0L0R) 0x0000) 

tdefine sysDcInkGray66 ( (SYSDC_COLOR) 0x0001) 

tdefine sysDdnkGray33 ( (SYSDC_COLOR) 0x0002) 

tdefine sysDcInkWhite ( (SYSDC_C0L0R) 0x0003) 



msgDcMatchRGB 

Returns palette entry that best matches an RGB. 
Takes U32, returns SYSDC_COLOR. 

tdefine msgDcMatchRGB MakeMsg(clsSysDrwCtx, 10) 

This interface is NOT RECOMMENDED for application software. Set colors directly using the 
msgDcSetForegroundRGB and msgDcSetBackgroundRGB messages. 
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msgDcSetForegroundColor 

Sets foreground color using a hardware palette index, returning old color. 
Takes SYSDQCOLOR, returns SYSDC.COLOR. 

tdefine msgDcSetForegroundColor MakeMsg(clsSysDrwCtx, 5) 

Comments This interface is NOT RECOMMENDED for application software. Use msgDcSetForegroundRGB 

instead of this message. 

When using this interface, see the constants sysDcInk... for predefined palette index values. 



msgDcSetBackgroundColor 

Sets background color using a hardware palette index, returning old color. 
Takes SYSDC_COLOR, returns SYSDC_COLOR. 

tdefine msgDcSetBackgroundColor MakeMsg(clsSysDrwCtx, 6) 

Comments This interface is NOT RECOMMENDED for application software. Use msgDcSetBackgroundRGB 

instead of this message. 

When using this interface, see the constants sysDcInk... for predefined palette index values. 



Arguments 



msgDcMixRGB 



Programs a palette slot to a specific RGB. 

Takes P_SYSDC_MIX_RGB, returns STATUS. 

tdefine msgDcMixRGB MakeMsg(clsSysDrwCtx, 80) 

typedef struct 
{ 

SYSDC_COLOR slot; 

SYSDC_RGB spec; 

} SYSDC_MIX_RGB, * P_SYSDC_MIX_RGB; 

*** NOT IMPLEMENTED YET *** 

This interface is NOT RECOMMENDED for application software. The type SYSDC_MIX_RGB is 
defined now to support msgWinDevMixRGB. 



msgDcSetLinePat 

Sets the line pattern; returns old value. 

Takes SYSDC_PATTERN, returns SYSDC_PATTERN. 



tdefine msgDcSetLinePat 
typedef U16 SYSDC_PATTERN; 
tdefine sysDcPat75 
tdefine sysDcPat50 
tdefine sysDcPat25 
tdefine sysDcPatl2 
tdefine sysDcPat6 
tdefine sysDcPat3 
tdefine sysDcPat2 
tdefine sysDePatLD50 
tdefine sysDcPatLD37 
tdefine sysDcPatLD25 
tdefine sysDcPatLDl2 
tdefine sysDcPatRD50 



MakeMsg(clsSysDrwCtx, 11) 



(SYSDC_PATTERN)1) 

(SYSDC_PATTERN)2) 

(SYSDC_PATTERN)3) 

(SYSDC_PATTERN)4) 

(SYSDC_PATTERN)5) 

(SYSDC_PATTERN) 6) 

(SYSDC_PATTERN)7) 

(SYSDC_PATTERN)8) 

(SYSDC_PATTERN) 9) 

(SYSDC_PATTERN)10) 

(SYSDC_PATTERN)11) 

(SYSDC PATTERN) 12) 



// 
// 
// 
// 
// 
// 
// 



75% fgnd 
50% fgnd 
25% fgnd 
12% fgnd 
6% fgnd 
3% fgnd 
2% fgnd 
// darkest 
II 
II 



25% bgnd 

50% bgnd 

75% bgnd 

88% bgnd 

94% bgnd 

97% bgnd 

98% bgnd 
left diagonal 
left diagonal 
left diagonal 



// lightest left diagonal 
// darkest right diagonal 
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♦define sysDcPatRD37 ( (SYSDC_PATTERN) 13) // right diagonal 

♦define sysDcPatRD25 ( (SYSDC_PATTERN) 14) // right diagonal 

#define sysDcPatRDl2 ( (SYSDC_PATTERN) 15) // lightest right diagonal 

♦define sysDcPatBackground ( (SYSDC_PATTERN)0) // 0% fgnd 100% bgnd 

♦define sysDcPatForeground ( (SYSDC_PATTERN)0xFFFl) // 100% fgnd 0% bgnd 

♦define sysDcPatNil ( (SYSDC_PATTERN)0xFFF0) // 0% fgnd 0% bgnd 

♦define sysDcPatRandom ( (SYSDC_PATTERN)0xFFF2) // debugging aid 

Comments The line pattern is used to draw lines around the edge of geometric figures when the line thickness 

is > 0. 

When using this interface, see the constants sysDcPat... for predefined patterns. 

^^^^^^^—^^—^—^^^^—^^^^ 

Sets the fill pattern; returns old value. 

Takes SYSDC.PATTERN, returns SYSDC.PATTERN. 

♦define msgDcSetFillPat MakeMsg(clsSysDrwCtx, 12) 

Comments The fill pattern is used to draw the interior of closed geometric figures. 

When using this interface, see the constants sysDcPat... for predefined patterns. sysDcPatRandom is 
unique for each window. 

msgDcGetLinePat 

Gets the line pattern. 

Takes pNull, returns SYSDC.PATTERN. 

♦define msgDcGetLinePat MakeMsg(clsSysDrwCtx, 13) 

comments *** NOT IMPLEMENTED YET *** 



msgDcGetFillPat 

Gets the fill pattern. 

Takes pNull, returns SYSDC.PATTERN. 

♦define msgDcGetFillPat MakeMsg(clsSysDrwCtx, 14) 

*mi«e«ts *** NOT IMPLEMENTED YET *** 



msgDcMixPattern 

Mixes a custom pattern. 

Takes P_SYSDC_MIX_PAT, returns STATUS. 

♦define msgDcMixPattern MakeMsg(clsSysDrwCtx, 15) 

Arguments typedef struct 

{ 

S YSDC_P ATTERN s lot ; 

U8 pattern [8] ; 

} SYSDC_MIX_PAT, * P_SYSDC_MIX_PAT ; 

Comments *** NOT IMPLEMENTED YET *** 
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msgDcAlignPattern 

Sets the pattern alignment in LUC. 

Takes P_XY32, returns STATUS. 

♦define msgDcAlignPattern MakeMsg(clsSysDrwCtx, 16) 

Comments Can be used to keep pattern tiling aligned to a particular point in LUC when pixels are moved 

(msgWinCopyRect or wsGrow* flags). This is most commonly used to preserve pattern alignment 
during "scrolling" when parts of an image are copied pixels, and parts are newly painted pixels. 

The default alignment is 0,0 in LUC. If the image is scrolled by msgDcTranslate then this message may 
not be necessary, as the alignment point will move in device space too. 

If P_XY32 is pNull, default alignment is set to 0,0. 



LUC Space Transformations 



msgDcUnitsMetric 

Sets input units to 0.01 mm. 
Takes pNull, returns stsOK. 

♦define msgDcUnitsMetric 



MakeMsg(clsSysDrwCtx, 17) 



msgDcUnitsMil 

Sets input units to 0.001 inch. 
Takes pNull, returns stsOK. 

♦define msgDcUnitsMil 



MakeMsg(clsSysDrwCtx, 18) 



msgDcUnitsPoints 

Sets input units to points (1/72 of an inch). 

Takes pNull, returns stsOK. 

♦define msgDcUnitsPoints MakeMsg(clsSysDrwCtx, 19) 



msgDcUnitsTwips 

Sets input units to 1/20 of a point. 
Takes pNull, returns stsOK. 

♦define msgDcUnitsTwips 



MakeMsg(clsSysDrwCtx, 20) 



msgDcUnitsPen 

Sets input units to pen sample units. 
Takes pNull, returns stsOK. 
♦define msgDcUnitsPen 



MakeMsg(clsSysDrwCtx, 71) 
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msgDcUnitsLayout 

Sets input units to UI toolkit layout units. 

Takes pNull, returns stsOK. 

#define msgDcUnitsLayout MakeMsg(clsSysDrwCtx, 85) 

Note that the scale this implicitly computes is a function of the current system font size. However, if the 
system font size changes after this message is sent, the scale is not "reliably" reevaluated (because of 
caching it may or may not be reevaluated). Thus, you may need to observe theSystemPreferences. For a 
small performance cost you can just send this message prior to each operation that is affected by unit 
scaling. 

msgDcUnitsRules 

Sets input units to the 'rules' associated with the system font. 

Takes pNull, returns stsOK. 

#define msgDcUnitsRules MakeMsg(clsSysDrwCtx, 3) 

Comments A rule' is 1/20 of the thickness of a line that aesthetically matches the weight of the system font, as 

specified by the font designer. Typically this will be the thickness of a single underline, and so a rule 
would be 1/20 of an underline. 

Note that the scale this implicitly computes is a function of the current system font size. However, if the 
system font size changes after this message is sent, the scale is not "reliably" reevaluated (because of 
caching it may or may not be reevaluated). Thus, you may need to observe theSystemPreferences. For a 
small performance cost you can just send this message prior to each operation that is affected by unit 
scaling. 

msgDcUnitsDevice 

Sets input units to device pixels. 

Takes pNull, returns stsOK. 

tdefine msgDcUnitsDevice MakeMsg(clsSysDrwCtx, 21) 



msgDcUnitsWorld 

Sets input units to an arbitrary number of device pixels. 
Takes pNull, returns stsOK. 

tdefine msgDcUnitsWorld MakeMsg(clsSysDrwCtx, 25) 

See Also msgDcScaleWorld 

msgDcUnitsOut 

Sets output units produced by transformation of input units. 
Takes MESSAGE, returns stsOK. 

#define msgDcUnitsOut MakeMsg(clsSysDrwCtx, 70) 

Comments Takes one of: 

msgDcUnitsMetric 
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In general, this message should not be used. Reverse transformations, from device units to other units 

can be made by using the msgDcLUCtoLWC... messages. M 

This interface can be used to change from one logical unit system to another. Since most such £ 

transformations are known in advance this is generally useless; however, transformation to and from pen g 

units to a known unit system is the real purpose of this interface. For instance, pen units to mils can be °* 

used to store pen units in a device independent form. Pen units can thus remain device dependent. 5 

This interface cannot change a graphic device unit into a device independent unit. To do this, units IN £ 

must be the chosen target unit (e.g. points), units OUT must be device, and the reverse transformation, 
msgDcLUCtoLWC must be used. 

msgDcIdentity 

Sets LUC matrix to identity. 
Takes pNull, returns stsOK. 

tdefine msgDcIdentity MakeMsg(clsSysDrwCtx, 22) 

See Also msgDcIdentityFont 

msgDcRotate 

Rotates LUC matrix. 

Takes ANGLE, returns stsOK. 

#define msgDcRotate MakeMsg(clsSysDrwCtx, 23) 

msgDcScale 

Scales LUC matrix. 
Takes P_SCALE, returns stsOK. 

tdefine msgDcScale MakeMsg(clsSysDrwCtx, 26) 

Comments If P_SCALE is pNull then operation is same as msgDcIdentity. 

msgDcScaleWorld 

Creates a world scale of window width/height. 

Takes P_SIZE32, returns stsOK. 

tdefine msgDcScaleWorld MakeMsg(clsSysDrwCtx, 61) 

Comments The window width/height is divided into SIZE32 width/height units. If the window is not physically 

square on the graphic device then the scale will not be uniform in x and y. 

This message scales the LUC matrix. Typically, this matrix must be reset to identity (msgDcIdentity), 
and this message must be resent, whenever the window changes size (see msgWinSized for help). 

The DC must be bound to a window when it receives this message. 

msgDcTranslate 

Translates LUC matrix. 

Takes P_XY32, returns stsOK. 

tdefine msgDcTranslate MakeMsg(clsSysDrwCtx, 24) 
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Coordinate Conversion 

These messages convert coordinates from LUC to LWC, or LWC to LUC. The DC must be bound to a 
window before it receives these messages. 

Transforms a point from window (device) space to logical space. 
Takes P_XY32, returns stsOK. 

tdefine msgDcLWCtoLUC_XY32 MakeMsg(clsSysDrwCtx, 27) 

mts The DC transforms by: 

LWC — > fractional LUC — > round to nearest integer LUC 

Transforms a point from logical space to window (device) space. 

Takes P_XY32, returns stsOK. 

#define msgDcLUCtoLWC_XY32 MakeMsg(clsSysDrwCtx, 39) 

Comments The DC transforms by: 

LUC — > fractional LWC --> round to nearest integer LWC 
— _«-^ _^ _____ 

Transforms a size from window (device) space to logical space. 

Takes P_SIZE32, returns stsOK. 

tdefine msgDcLWCtoLUC_SIZE32 MakeMsg(clsSysDrwCtx, 44) 

Comments The DC transforms by: 

LWC — > fractional LUC — > round to nearest integer LUC --> AbsQ 
-____^ _____ ^—^^—^—^—^ 

Transforms a size from logical space to window (device) space. 

Takes P_SIZE32, returns stsOK. 

#define msgDcLUCtoLWC_SIZE32 MakeMsg(clsSysDrwCtx, 45) 

Comments The DC transforms by: 

LUC — > fractional LWC — > round to nearest integer LWC — > Abs() 

__^^_^___ ^————^ 

Transforms a rectangle from window (device) space to logical space. 
Takes P_RECT32, returns stsOK. 

tdefine msgDcLWCtoLUC_RECT32 MakeMsg(clsSysDrwCtx, 46) 

Comments The DC transforms by: 

1) converting the rectangle's origin and opposite corner (x+w, y+h) 
into fractional LUC, 
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2) rounding each point to the nearest integer coordinate, and 

3) using those coordinates to determine a rectangle (whose width and J5 

i 
height may be positive or negative). < 



n 



msgDcLUCtQLWC_RECT32 

Transforms a rectangle from logical space to window (device) space. S 

Takes P_RECT32, returns stsOK. 

tdefine msgDcLUCtoLWC_RECT32 MakeMsg(clsSysDrwCtx, 47) 

Comments The DC transforms by: 

1) converting the rectangle's origin and opposite corner (x+w, y+h) 
into fractional LWC, 

2) rounding each point to the nearest integer coordinate, and 

3) using those coordinates to determine a rectangle (whose width and 
height may be positive or negative). 



msgDcGetMatrix 

Returns the LWC matrix. 

Takes P_MAT, returns stsOK. 

tdefine msgDcGetMatrix MakeMsg(clsSysDrwCtx, 40) 

The DC must be bound to a window when this message is sent. This matrix transforms LUC to LWC 
(first quadrant, but device dependent units) coordinates. These coordinates are suitable for positioning 
windows. 

msgDcGetMatrixLUC 

Returns the LUC matrix. 

Takes P_MAT, returns stsOK. 

tdefine msgDcGetMatrixLUC MakeMsg(clsSysDrwCtx, 87) 

This matrix combines transformations to LUC space. It is identity unless msgDcScale, msgDcRotate, 
msgDcTranslate, msgDcScaleWorld, or msgDcSetMatrixLUC have been previously sent. 

The default for these combinations is post-multiplication. See message msgDcSetPreMultiply for more 
on this subject. 



msgDcSetMatrixLUC 

Replaces the LUC matrix. 

Takes P_MAT, returns stsOK. 

tdefine msgDcSetMatrixLUC MakeMsg(clsSysDrwCtx, 88) 
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Clipping 



msgDcClipRect 

Sets or clears clip rectangle. 
Takes P_RECT32 or pNull, returns stsOK. 

tdefine msgDcClipRect MakeMsg(clsSysDrwCtx, 28) 

Commetits If P_RECT32 is pNull then operation is same as msgDcClipClear. 



msgDcClipClear 

Returns clipping to entire window. 

Takes pNull, returns stsOK. 

♦define msgDcClipClear MakeMsg(clsSysDrwCtx, 29) 



msgDcClipNull 

Suspends all clipping (except to raw device). 

Takes pNull, returns stsOK. 

tdefine msgDcClipNull MakeMsg(clsSysDrwCtx, 30) 

Comments The pen handler uses this to dribble ink anywhere on-screen (in the pen plane(s) only). 

This interface is NOT RECOMMENDED for application software. It will protection fault if the caller 
does not have hardware privilege. 



Hit Detection 



msgDcHitTest 

Turns hit testing on/off. 

Takes P_RECT32 or pNull, returns stsOK. 

tdefine msgDcHitTest MakeMsg (clsSysDrwCtx, 66) 

Comments To turn hit testing on supply a rectangle to test against. To turn hit testing off send pNull. 

In general, drawing messages (msgDcDraw...) will return one of the status values stsDcHit... if hit 
testing is on: 

stsDcHitOn if the line intersects the hit rectangleif the rectangle is inside a closed figureif there was no 
hit 

The following drawing messages implement hit testing: 

msgDcDrawPolyline 

(^Bounds Accumulation 

A region is available to accumulate the bounding rectangles of drawing operations. 
msgDcAccumulateBounds(pNull) clears this region to empty and turns on accumulation. At this point, 
as in hit testing, drawing operations will not be output; rather, their bounding rectangles will be added 
to the accumulation. At any time the accumulation can be retrieved by using msgDcGetBounds. It can 



msgDcAccumulateBounds 

Starts or stops bounds accumulation; retrieve bounds. 

Takes P_RECT or pNull, returns stsOK. 

#define msgDcAccumulateBounds MakeMsg (clsSysDrwCtx, 81) 

Comments If pArgs is pNull, clears current accumulation and turns accumulation on. If pArgs is P_RECT32, returns 

accumulated bounds, and turns bounds accumulation off. 

The DC computes the LUC rectangle so that it: 

1) mathematically includes all of the accumulated pixels, and 

2) has non-negative width and height. 

msgDcDirtyAccumulation 

Marks accumulation dirty; turns accumulation off; retrieves bounds. 

Takes P_RECT32 or pNull, returns stsOK. 

#define msgDcDirtyAccumulation MakeMsg (clsSysDrwCtx, 82) 

Comments Adds current bounds accumulation directly to the dirty region of the current window; then clears 

current bounds accumulation and turns accumulation off. If pArgs is P_RECT32, returns accumulated 
bounds as in msgDcAccumulateBounds. 



msgDcGetBounds 

Retrieves current accumulation bounds rectangle. 

Takes P_RECT32, returns stsOK. 

tdefine msgDcGetBounds MakeMsg (clsSysDrwCtx, 83) 
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be retrieved with another call to msgDcAccumulateBounds (P_RECT32); which will both retrieve it, and 

turn off accumulation so normal drawing can resume. M 

u 

Normally, bounds are accumulated for the purpose of repainting part of a window. a. 

msgDcDirtyAccumulation can be used to add the accumulation directly to the dirty region of the g 

current window. This is more efficient than getting the bounds rectangle and then sending * 

msgWinDirtyRect. £ 

Bounds accumulation occurs in DU4 space; while the bounds rectangle is returned in LUC, it always z 

represents a rectangle in DU4. Thus, drawing which is clipped because of windowing, or because it falls 
off the edges of the device, is not accumulated. 

The bounds accumulation region itself is not part of the logical state, although the flag that determines 
whether drawing operations accumulate or draw is part of the logical state. Thus, while calls to push and 
pop the state may turn accumulation on or off, there are not separate copies of the accumulation region 
itself in the state. 

Bounds accumulation and hit testing cannot be performed at the same time. If, through program error, 
both modes are enabled, bounds accumulation will take priority. 

Neither bounds accumulation or hit testing should be used during repainting initiated by the window 
manager sending msgWinRepaint. Rather, they should be used within a msgWinBeginPaint 
msgWinEndPaint bracket. 
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Arguments typedef struct 

{ 

U16 count; // number of points in points array 

P_XY32 points; // pointer to array of at least 2 points 
} SYSDC_POLYGON , * P_SYSDC_POLYGON , 

SYSDC_POLYLINE, * P_SYSDC_POLYLINE; 
typedef struct 
{ 

RECT32 bounds; 

XY32 rays [2]; 
} SYSDC_ARC_RAYS, * P_SYSDC_ARC_RAYS ; 

Comments Does not clear accumulation or turn accumulation off. The DC computes the LUC rectangle as in 

msgDcAccumulateBounds. 



Open Figures 



msgDcDrawPolyline 

Draws a line; needs at least 2 points. Returns either hit test or stsOK. 
Takes P_SYSDC_POLYLINE, returns STATUS. 

#define msgDcDrawPolyline MakeMsg(clsSysDrwCtx, 100) 

Return Valye StsDcHitOn 



msgDcDrawBezier 

Draws a Bezier curve; needs exactly 4 points. 
Takes P_XY32 (array of 4), returns STATUS. 

#define msgDcDrawBezier MakeMsg(clsSysDrwCtx,104) 

imments Returns either hit test or stsOK. 

s*«ra Value StsDcHitOn 



msgDcDrawArcRays 

Draws an arc using the two rays method. Returns either hit test or stsOK. 

Takes P_SYSDC_ARC_RAYS, returns STATUS. 

♦define msgDcDrawArcRays MakeMsg(clsSysDrwCtx,105) 



Message typedef struct 

Arguments { 



RECT32 bounds; 
XY32 rays [2]; 
} SYSDC_ARC_RAYS, * P_SYSDC_ARC_RAYS ; 

StsDcHitOn 
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|F Closed Figures 



msgDcSetPixel 

Sets a pixel with a value. 

Takes P_SYSDC_PIXEL, returns STATUS. 

tdefine msgDcSetPixel MakeMsg(clsSysDrwCtx, 108) 

Comments If rgb is true, the color is interpreted as an RGB value; if not, color.all will be interpreted as a 

SYSDC_COLOR (a hardware palette index). If rgb is used then the transparency byte must be 255 
(opaque) or the drawing will not take place. 

msgDcGetPixel 

Gets a pixel value. 

Takes P_SYSDC_PIXEL, returns STATUS. 

#define msgDcGetPixel 

typedef struct 
{ 

BOOLEAN rgb; 

SYSDC_RGB color; 

XY32 xy; 

} SYSDC PIXEL, * P SYSDC PIXEL; 



Arguments 



Return Vc 



MakeMsg(clsSysDrwCtx, 109) 



If rgb is TRUE the color is returned as an RGB value; if not color.all will be a small number which 
should be interpreted as a SYSDC_COLOR (a hardware palette index). If rgb is used the transparency byte 
will always be returned as 255 (opaque). 



Return Value 



msgDcDrawRectangle 

Draws a rectangle. Returns either hit test or stsOK. 

Takes P_RECT32, returns STATUS. 

tdefine msgDcDrawRectangle MakeMsg(clsSysDrwCtx,101) 

stsDcHitOn 

msgDcDrawEUipse 

Draws an ellipse. Returns either hit test or stsOK. 

Takes P_RECT32, returns STATUS. 

tdefine msgDcDrawEUipse MakeMsg(clsSysDrwCtx, 102) 

stsDcHitOn 



Message 
Arguments 



Returm Value 



msgDcDrawPolygon 

Draws a polygon. Returns either hit test or stsOK. 

Takes P_SYSDC_POLYGON, returns STATUS. 

tdefine msgDcDrawPolygon MakeMsg(clsSysDrwCtx, 103) 

typedef struct 

{ 
U16 count; // number of points in points array 

P_XY32 points; // pointer to array of at least 2 points 

} SYSDC_POLYGON , * P_SYSDC_POLYGON , 

stsDcHitOn 
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msgDcDrawSectorRays 

Draws a sector (pie wedge) using the two rays method. 

Takes P_SYSDC_ARC_RAYS, returns STATUS. 

tdefine msgDcDrawSectorRays MakeMsg(clsSysDrwCtx,106) 

Messoge typedef struct 

Arguments { 

RECT32 bounds; 

XY32 rays [2]; 
} SYSDC_ARC_RAYS, * P_SYSDC_ARC_RAYS; 

CommeRts Returns either hit test or stsOK. 

Return ¥olue StsDcHitOn 



msgDcDrawChordRays 

Draws a chord using the two rays method. Returns either hit test or stsOK. 

Takes P_SYSDC_ARC_RAYS, returns STATUS. 

#define msgDcDrawChordRays MakeMsg(clsSysDrwCtx, 107) 



Messoge typedef struct 

Arguments { 

RECT32 bounds; 

XY32 rays [2]; 
} SYSDC_ARC_RAYS, * P_SYSDC_ARC_RAYS ; 

Return Value StsDcHitOn 

msgDcFillWindow 

Frames window with a line and fills the window. 

Takes pNull, returns stsOK. 

tdefine msgDcFillWindow MakeMsg(clsSysDrwCtx, 33) 

Comments Draws a rectangle exactly the size of the window. All line, fill and color attributes apply. 

When drawing a rectangle, the first pixel of line thickness is painted "inside" the rectangle, the second 
"outside", and it alternates from there. Therefore, lines > 1 pixel thick will have 1/2 their thickness fall 
outside the window when using this message. If that drawing is clipped (as it normally is) the line will 
appear 1/2 as thick as one would expect. 



Sampled Image Processing 



msgDcDrawImage 

Draws an image from sampled image data. The image will be scaled, rotated, translated, according to the 
current state. 

Takes P_SYSDC_IMAGE_INFO, returns STATUS. 



#define msgDcDrawImage MakeMsg(clsSysDrwCtx, 48) 

tdefine msgDcGetSrcRow MakeMsg(clsSysDrwCtx, 49) 
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comments 



Enuml6 (SYSDC_IMAGE_FLAGS) 

{ 
sysDcImageNoFilter 
sysDcImageLoFilter 
sysDdmageHiFilter 
sysDdmageRunLength 
sysDcImagelBPS 
sysDcImage2BPS 
sysDdmage4BPS 
sysDcImage8BPS 
sysDcImageCallBack 
sysDcImageCallObject 
sysDdmageFillWindow 
sysDdmagePolarityFalse 

}; 

typedef struct SYSDC_IMAGE 

typedef BOOLEAN FunctionPt 

typedef struct SYSDC IMAGE 



0, 


// fast but poor fidelity 


flagO, 


// use this for most image data 


flagl, 


// use this for color image data 


flag2, 


// run length encoded 


flag3, 


// 1 bit per sample 


(flag2|flag3) , // 2 bits per sample 


flag4, 


// 4 bits per sample 


0, 


// 8 bits per sample 


flag8, 


// callBack is a P_SYSDC_GETROW function 


flag9, 


// callBack is a OBJECT 


flaglO, 


// dstRect not provided 


flagll 


// paint '0' w/ background color 




// else paint '1' w/ foreground color 



RECT32 




dstRect; 


SIZE16 




srcSize; 


SYSDC_IMAGE_ 


_FLAGS 


flags ; 


union 






P_SYSDC_GETROW 


function; 


OBJECT 
} 




object; 
callBack; 


PJJNKNOWN 




pBuffer; 


PJJNKNOWN 




pClientData; 


PJJNKNOWN 




reserved [3] ; 


} SYSDC IMAGE 


INFO; 





INFO * P_SYSDC_IMAGE_INFO; 
r (P_SYSDC_GETROW) (P_SYSDC_IMAGE_INFO pCtx) ; 

INFO 



// destination size and position 
// # of source samples 



This message is similar to the PostScript image operator. Sample data, in the form of numbers ranging 
from 0..max are interpreted as grey values. is black and max is white. The value of max is determined 
by the size of the input numbers, which can be 1, 2, 4 or 8 bits. 

Because the sample data may be large, in a file, or incrementally decompressed, this message can work 
with a callback strategy. The callback can be either a function (flag sysDcImageCallBack), or an object 
(flag sysDcImageCallObject) to which msgDcGetSrcRow is sent. In both cases the argument is the 
same pointer to a SYSDC_IMAGE_INFO that is the argument to msgDcDrawImage itself. To support 
client context during the callback, the field pClientData is provided, for the callback to use as necessary. 

The source sample data width and height is described by srcSize. The rectangle at the destination, which 
will be filled by the image, is dstRect; or optionally, the flag sysDdmageFillWindow can be used to fill 
the entire window. 

During the callback, pBuffer will point to a buffer that needs to be filled with srcSize.w samples. If 
pBuffer is pNull, it means the operator is skipping a row (because of clipping perhaps). Thus, no 
samples need to be provided, but the context must be "advanced" to skip the row. If anything goes 
wrong, the callback can return FALSE (for a function), or a bad status code (for an object) to terminate 
the drawing. 

If callback is not used at all, then pBuffer should be set by the caller to point to all of the sample data at 
the outset. 

The result of the drawing is that dstRect is filled with an image. Since dstRect is in LUC space, its size 
and location is the same as if it were drawn with msgDcDrawRectangle. 
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Before using this interface to display "tiff images, investigate clsTiff (tifF.h) for a much higher level 
service. 

Return Value StsDcHitOn 

msgDcDrawImageMask 

Draws a mask from sampled image data. Similar to msgDcDrawImage. 

Takes P_SYSDC_IMAGE_INFO, returns STATUS. 

fdefine msgDcDrawImageMask MakeMsg(clsSysDrwCtx, 97) 

Message typedef struct SYSDC_IMAGE_INFO 

Argymenfs { 

RECT32 dstRect; // destination size and position 

SIZE16 srcSize; // # of source samples 

SYSDC_IMAGE_FLAGS flags; 
union 
{ 

P_SYSDC_GETROW function; 

OBJECT object; 

} callBack; 

P_UNKNOWN pBuffer; 

P_UNKNOWN pClientData; 

P_UNKNOWN reserved [3]; 
} SYSDC_IMAGE_INFO; 

Comments This message is similar to the PostScript imagemask operator and msgDcDrawImage. The input 

parameters are the same as for msgDcDrawImage with the addition of one flag, 
sysDcImagePolarityFalse, which would normally not be set (TRUE). However, the results of this 
message are visually different than msgDcDrawImage. 

msgDcDrawImage reduces the input data to grey values and paints an opaque parallelogram. The values 
of the current foreground and background colors have no effect on the behavior of msgDcDrawImage. 

msgDcDrawImageMask reduces the input data to the values '0' and '1'. The default behavior is for the 
' 1 ' values to be painted with the current foreground color; the '0' values are not painted at all. 

This behavior can be reversed by setting the sysDcImagePolarityFalse flag. In this case the '0' values are 
painted with the current background color and the ' 1 ' values are not painted. 

tetura Volye StsDcHitOn 

msgDcCachelmage 

Passes back a cached image in pCache, given a sampled image and an optional mask. 
Takes P_SYSDC_CACHE_IMAGE, returns STATUS. 
♦define msgDcCachelmage MakeMsg(clsSysDrwCtx, 91) 

Arguments typedef struct 

{ 

SYSDC_IMAGE_INFO image [2]; // in = [0] is image, [1] is mask 

BOOLEAN hasMask; // in = if this is true 

XY16 hotSpot; // in 

P_UNKN0WN pCache; // out = cache (segment) 

} SYSDC_CACHE_IMAGE, * P_SYSDC_CACHE_IMAGE; 

Comments A "cached image" is a segment of memory (pCache) that contains the device-dependent (pixelmap) 

representation of a sampled image (see msgDcDrawImage), and optionally a mask. 

This operator is intended to be used for cursors and icons. It currently does not work on printer devices. 



SYSGRAF.H 279 

Fonts 

Once cached, the image can be drawn (with hotspot adjustment) using msgDcCopylmage. 

Because of its device dependent representation, a cached image becomes obsolete when the device 3 

rotation changes (landscape vs. portrait). Thus, you may need to observe theSystemPreferences and £ 

rebuild the cache when appropriate. When you are finished with the cached image you should free it g 

with OSHeapBlockFree. °* 

o 
msgDcCopylmage | 

Copies a cached image to the bound window. 

Takes P_SYSDC_COPY_IMAGE, returns STATUS. 

♦define msgDcCopylmage MakeMsg(clsSysDrwCtx, 92) 

Arguments typedef struct 

{ 

XY32 xy; // in = destination location 

PJJNKNOWN pCache; //in 

} SYSDC_COPY_IMAGE, * P_SYSDC_COPY_IMAGE; 

Comments The image is copied, such that the hotspot aligns on xy. 

(F Fonts 

Some of the data structures used in the font interface are declared in sysfont.h. 

All font metric information is currently computed in LUC space. However, because all the relevant 
numbers, except for scaling, are integers, significant round-off error can occur. For instance, at 10 or 12 
points, a small feature, like x-height, will be a very small number. If LUC is relatively coarse, the error 
may be significant. The same holds true for the quality of inter-character spacing. Each character within 
a string of text output is positioned in LUC space, and the positioning will be no more accurate than the 
granularity of LUC. In general, the use of TWIPS units, or even finer units, is recommended if high 
quality text at small point sizes is required. Note that this may change in the future—read on. 

While this approach produces less than perfect results on screen, it does have the benefit of maintaining 
very close correspondence between screen and printer; such that the same code can be used for both 
with no significant variance. In general, each character will be positioned to within one LUC unit or one 
device pixel (whichever is larger), of accuracy. 

In future versions, the text measurement messages may change so that they advance character by 
character in an internal coordinate space that doesn't match LUC. This would allow accurate 
intercharacter spacing regardless of the granularity of LUC. 



SysDcFontld 

Takes a 4 byte string font description and returns a 16-bit font id number. 
Returns U16. 

U16 EXPORTED SysDcFontld (P_CHAR // In: a string like "HE55" 

); 
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SysDcFontString 

Takes a 1 6-bit font id number and passes back a 4 char string. 
Returns void. 

void EXPORTED SysDcFontString (Ul 6, // In: a font id number 

P_CHAR // Out: a string like "HE55" 
); 

Comments The string buffer should be at least 5 bytes long. 

msgDcOpenFont 

Opens a font. 

Takes P_SYSDC_FONT_SPEC or pNull, returns stsOK. 
tdefine msgDcOpenFont MakeMsg(clsSysDrwCtx, 53) 

Comments Specifying pNull will open default font. 



msgDcScaleFont 

Scales font matrix. 

Takes P_SCALE or pNull, returns stsOK. 

tdefine msgDcScaleFont MakeMsg(clsSysDrwCtx, 54) 

Comments If argument is pNull then behavior is same as msgDcIdentityFont. The default size of a newly opened 

font is 1 unit (LUC). Use this message to scale to the desired size. 

Note that this scaling is cumulative (multiplicative). A scale of 10,10 followed by a scale of 12,12 will 
result in a scale of 120,120. When "switching to absolute sizes" a msgDcIdentityFont will usually be 
needed. 

Note also that font scale is affected by the overall scale established by the msgDcUnits... messages, and 
msgDcScale. 

msgDcIdentityFont 

Sets font matrix scale to default of 1 unit (LUC). 

Takes pNull, returns stsOK. 

#define msgDcIdentityFont MakeMsg(clsSysDrwCtx, 72) 

msgDcDrawText 

Draws text in the current font. 

Takes P_SYSDC_TEXT_OUTPUT, returns stsOK. 

tdefine msgDcDrawText MakeMsg(clsSysDrwCtx, 55) 

msgDcMeasureText 

Computes size of text and advances pArgs->cp accordingly. 

Takes P_SYSDC_TEXT_OUTPUT, returns stsOK. 

tdefine msgDcMeasureText MakeMsg(clsSysDrwCtx, 57) 
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Comments Measuring stops when stop is exceeded. Stop will normally be a "right margin". This is used to measure 

out lines of text from a large buffer. Upon return lenText will be the number of characters that "fit". 
This information can then be used to break and justify lines. 

To simply measure an entire string, set cp.x = and stop = maxS32; upon return cp.x will be the length 



o 



of the string in LUC. eg 



«/> 



During measuring, other parameters, like spaceExtra and otherExtra are significant. § 

a 
Z 



msgDcDrawTextRun 

Like msgDcDrawText, except run spacing applies. 

Takes P_SYSDC_TEXT_OUTPUT, returns stsOK. 

#define msgDcDrawTextRun MakeMsg(clsSysDrwCtx, 73) 

Comments Run spacing is important when spaceExtra and otherExtra contain non-zero values; especially when 

underlining. For instance, if otherExtra is 10, then 10 units will be added after the last character when 
using run spacing. It would not be added when using the normal DrawText message. This affects the 
cp.x value returned, and is visually significant when underlining or strikethrough are performed (the 10 
units would have the lines or not). It will also affect the result when centering or right-justifying text. 



msgDcMeasureTextRun 

Like msgDcMeasureText, except run spacing applies. 
Takes P_SYSDC_TEXT_OUTPUT, returns stsOK. 
♦define msgDcMeasureTextRun MakeMsg(clsSysDrwCtx, 74) 

Comments See comments about "run spacing" under msgDcDrawTextRun. 

msgDcDrawTextDebug 

Like msgDcDrawText, except text is drawn with debugging lines around each char. 
Takes P_SYSDC_TEXT_OUTPUT, returns stsOK. 
♦define msgDcDrawTextDebug MakeMsg(clsSysDrwCtx ; 56) 

Comments This function may not work unless the debugging version ofwin.dll is being used. 

msgDcPreloadText 

Preloads pText into cache. 

Takes P_SYSDC_TEXT_OUTPUT, returns stsOK. 

♦define msgDcPreloadText MakeMsg(clsSysDrwCtx, 58) 

Comments If pArgs is pNull or pArgs->pText is pNull a default set is preloaded. 

This message causes the characters to be rasterized into the font cache so that during a subsequent 
msgDcDrawText there are no hesitations during a cache miss. This is not normally necessary, but might 
be useful in a "slide show" application. 



msgDcGetCharMetrics 

Gets char metrics information for a string. 

Takes P_SYSDC_CHAR_METRICS, returns stsOK. 

♦define msgDcGetCharMetrics MakeMsg(clsSysDrwCtx, 84) 
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Comments These character metrics are more precise in some ways than those returned by msgDcGetFontMetrics. 

For instance, the width of a character is a purely logical value. The character image may extend past its 
width to the right, and may extend to the left past its "left edge". Similarly, some characters will extend 
above the "ascender" line or below the "descender" lines (which are just imaginary lines that guide the 
letterforms in general). 

For each character in the string, the information returned is the minimum and maximum x and y 
coordinates found in that glyph, as if the glyph were drawn at 0,0. There are no "string semantics" to 
the "string" (x is not accumulating left to right); rather, this is similar to a "width table" except values for 
a specific string only are returned. 

See the caveat below for msgDcGetFontWidths. 



msgDcGetFontMetrics 

Gets the font metrics for the current font. 

Takes P_SYSDC_FONT_METRICS, returns stsOK. 

tdefine msgDcGetFontMetrics MakeMsg(clsSysDrwCtx, 59) 

msgDcGetFontWidths 

Gets the font width table of the current font. 

Takes P_SYSDC_FONT_WIDTHS, returns stsOK. 

#define msgDcGetFontWidths MakeMsg(clsSysDrwCtx, 60) 

Comments This width table is an array of 255 COORD16 values. Try to use the msgDcMeasureText interface 

instead; as width tables become less practical as character sets get larger and larger (e.g., Kanji). 

Another important reason to use msgDcMeasureText instead is that the measureText/drawText 
interfaces may change in the future to advance character by character in an internal coordinate space 
that doesn't match LUC. This would allow accurate intercharacter spacing regardless of the granularity 
of LUC. In short, we do not guarantee that merely adding up widths obtained by 
msgDcGetFontWidths would match the results of using msgDcMeasureText. msgDcMeasureText 
always represents the correct behavior, while msgDcGetFontWidths should be thought of as an 
approximation. 



Special Messages 



msgDcDrawPageTurn 

Draws a page turn effect over the bound window. 

Takes P_SYSDC_PAGE_TURN, returns stsOK. 

#define msgDcDrawPageTurn MakeMsg(clsSysDrwCtx, 86) 



Arguments typedef struct 
{ 



P_RECT32 pBounds; // may be pNull for entire window 
U16 fxNo, // must be 

iterations; 
BOOLEAN fxFwd, 

landscape; 
} SYSDC PAGE TURN, * P SYSDC PAGE TURN; 



»©mmenfs 
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msgDcCopyPixels 

Copies pixels from srcWindow to the bound window. ^ 

a. 

Takes P_SYSDC_PIXELS, returns stsOK. 2 

o 

#define msgDcCopyPixels MakeMsg(clsSysDrwCtx, 89) < 

Arguments typedef struct q 

o 

OBJECT srcWindow; // in=on a clsImgDev > 

P_RECT32 pBounds; // in=may be pNull for entire window 

XY32 xy; // in=destination location 

BOOLEAN dstDirty; // in= 

} SYSDC PIXELS, * P SYSDC PIXELS; 



{ 



Comments The rectangle pBounds on srcWindow is copied to the destination (bound) window at location xy. If 

dstDirty is TRUE, "dirty" pixels from the srcWindow cause the corresponding pixels on the destination 
window to be marked dirty (however, the dirty pixels ARE copied anyway). 

The srcWindow must be on an "image device". See clsImgDev. 

iet«rn VoSoe stsTruncatedData source rectangle not entirely on the window device; some dest pixels not affected. 

msgDcDrawPixels 

Draws foreground and background colors in the bound window's pixels using srcWindow's pixel values 
as a stencil. 

Takes P_SYSDC_PIXELS, returns stsOK. 

#define msgDcDrawPixels MakeMsg(clsSysDrwCtx, 90) 

Message typedef struct 

Argyments { 

OBJECT srcWindow; // in=on a clsImgDev 

P_RECT32 pBounds; // in=may be pNull for entire window 

XY32 xy; // in=destination location 

BOOLEAN dstDirty; // in= 
} SYSDC PIXELS, * P SYSDC PIXELS; 



Like msgDcCopyPixels except the source clsImgDev window must be only 1 plane and the dstDirty 
processing is not performed. 

' 1 ' pixels from the source are drawn with the foreground color, and '0' pixels with the background color. 

tetyro ¥«!ye stsTruncatedData source rectangle not entirely on the window device; some dest pixels not affected. 



msgDcScreenShot 

Captures a screen image to a "tiff file. 

Takes P_SYSDC_SCREEN_SHOT, returns stsOK. 

♦define msgDcScreenShot MakeMsg(clsSysDrwCtx, 67) 



Arguments typedef struct 

{ 



P_RECT32 pBounds; 
P_CHAR pFileName; 
} SYSDC_SCREEN_SHOT, * P_SYSDC_SCREEN_SHOT; 

pBounds can be a rectangle that is off the window and those pixels will be captured too (actually, 
wraparound will occur); no clipping is implied by the window, only the relative positioning of pBounds. 
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If pBounds is pNull the whole window will be captured. If LUC are rotated non-modulo 90 degrees an 
upright rectangle bounding pBounds will be captured. 

If you are just capturing screen shots for documentation, try using the SShot utility application first. 



Messages from other classes 



msgDrwCtxSetWindow 

Binds a window to the receiver and returns the previously bound window. 

Takes WIN, returns WIN. 

All output through the DC will now appear on this window. A DC must be bound to a window before 
most messages will work. 

msgDrwCtxGetWindow 

Gets the window to which the drawing context is bound. 
Takes pNull, returns WIN. 



msgWinDirtyRect 

Marks all or part of a window dirty. 

Takes P_RECT32 or pNull, returns STATUS. 

Comments If P_ARGS is not null, the DC will transform the rectangle into LWC and pass the message on to the 

DCs bound window. The DC computes the LWC rectangle in the same manner as 
msgDcAccumulateBounds, i.e. so that it: 

1) mathematically includes the entire LUC rectangle, and 

2) has non-negative width and height. 

If the P_ARGS is null, the DC will just pass the message on to the DCs bound window. 

msgWinBeginPaint 

Sets up window for painting on its visible region. 
Takes P_RECT32 or pNull, returns STATUS. 
Comments The P_ARGS is handled the same as in msgWinDirtyRect. 

msgWinBeginRepaint 

Sets up window for painting on "dirty" region. 

Takes P_RECT32 or pNull, returns STATUS. 

The DC will pass the message on to the DCs bound window and then, if P_ARGS is not null, transform 
the out parameter rectangle from LWC to LUC. The DC computes the rectangle so that it: 

1) mathematically includes the entire LUC rectangle, and 

2) has width and height >= 1. 
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Comments 



Comments 



Comment 



.ommenfs 



Comments 



msgWinBeginPaint 

Sets up window for painting on its visible region. 

Takes P_RECT32 or pNull, returns STATUS. 

The P_ARGS is handled the same as in msgWinBeginRepaint. 



msgWinDelta 

Moves and/or resizes a window. pArgs->bounds should be the newly desired bounds (size AND 
position). 

Takes P_WIN_METRICS, returns STATUS. 



The DC will transform pArgs->bounds into LWC and pass the message on to the DCs bound window. 
The DC transforms: 

the in parameter bounds in the same manner as msgDcLUCtoLWC_RECT32, and 

the out parameter bounds in the same manner as msgDcLWCtoLUC_RECT32. 

Transforms bounds from receiver's to another window's LWC. 

Takes P_WIN_METRICS, returns STATUS. 

The P_ARGS is handled the same as in msgWinDelta. 



msgWinHitDetect 

Locates the window "under" a point. 

Takes P_WIN_METRICS, returns STATUS. 

The DC will pass the message on to the DCs bound window. The bounds passed along to the window 
will be a copy of pArgs->bounds that the DC has transformed into LWC as in 
msgDcLUCtoLWC_RECT32. 



msgWinGetMetrics 

Gets full window metrics. 

Takes P_WIN_METRICS, returns STATUS. 

The DC will pass the message on to the DCs bound window, and then return a pArgs->bounds that is 
transformed as in msgDcLWCtoLUC_RECT32. 



msgWinCopyRect 

Copies pixels within a window. 

Takes P_WIN_COPY_RECT, returns STATUS. 

The DC will first transform the pArgs->srcRect from LUC to LWC as in msgWinDelta. The DC will 
then transform pArgs->xy: 

if wsCopyRelative is set, as in msgDcLUCtoD$ r C_SIZE32 

if wsCopyRelative is cleared, as in msgDcLUCtDLWC_XY32. 



comments 
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The DC will then pass the message on to the DCs bound window. 

Drawing contexts respond to every other clsWin message by just forwarding the message on to its 
bound window. The P_ARGS are not touched by the DC. 

msgWInDevBindPixelmap 

Binds window device to a pixelmap. 

Takes P_WIN_DEV_PIXELMAP, returns STATUS. 

The DC will pass the message on to pArgs->device. The pArgs->size passed along to the device will be a 
copy of pArgs->size that the DC has transformed into LWC by: 

1) setting up a local rectangle of x=0, y=0, w=pArgs->size.w, 
h=pArgs->size.h 

2) transforming this rectangle into LWC as in msgWinDirtyRect 
(using the transformation matrix of the DC), and 

3) setting the copied size to the resulting rectangle's size. 

The DC will also change the pArgs->device passed along to be the device on which the DCs bound 
window was created. 

msgWinDevSizePixelmap 

Computes the amount of memory needed for a single plane. 

Takes P_WIN_DEV_PIXELMAP, returns STATUS. 

#endif // SYSGRAF_INCLUDED 

Comments The P_ARGS is handled the same as in msgWinDevBindPixelmap. 

Drawing contexts respond to every other clsWinDev message by just forwarding the message on to its 
bound window. Note that clsWin's response to clsWinDev messages is to just call ancestor (except for 
messages sent to the root window on the device, which get passed on to the device). 

The P_ARGS are not touched by the DC. 
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TIFF.H 



This file contains the API definition for clsTiff (Tagged Image File Format). 

clsTiff inherits from clsObject. 

clsTiff provides decoding and display of TIFF file to a window. 

clsTiff remembers a pathname to a TIFF file; the file must be in the same location on redisplay. TIFF 
objects are not windows; they take a drawing context to repaint. 

clsTiff provides display of the black and white grey scale formats. It decodes compression types for 
packed data (type 1); Group3 (FAX) horizontial encoding (types 2 and 3); Pack Bits run-length (type 
32773). Samples per pixel are limited to 1,2, 4, or 8. TIFF images must be grey scale; it does not 
support colormap or direct color (RGB) images. It supports tags for photometric interpretion, fill order, 
orientation, dot size, Intel & Motorola byte order. 

Common uses of clsTiff: 

clsTiff can be the data object for a clsView object. It is used by the Fax Viewer in this way to display fax 
images. 

♦ifndef TIFF_INCLUDED 
tdefine TIFF_INCLUDED 

#ifndef PICSEG_INCLUDED 
tinclude "picseg.h" 
#endif 



Messages 



msgNewDefaults 

Initializes a TIFF_NEW structure to default values. 

Takes P_TIFF_NEW, returns STATUS. Category: class message. 

defaults: tiff.pName = pNull; tiff.imageFlags = sysDcImageFillWindow; tiff. rectangle = zeros; 



msgNew 

Creates a new TIFF object, and optionaly opens its associated file. 
Takes P_TIFF_NEW, returns STATUS. Category: class message. 

Arguments typedef Struct TIFF STYLE { 



1, 

.15; 

16; 



U16 save 

sparel 
U16 spare2 
}TIFF_STYLE, * P_TIFF_STYLE; 

typedef struct { 

P_U8 pName; 

SYSDC_IMAGE_FLAGS imageFlags; 

RECT32 rectangle; 

TIFF_STYLE style; 

S32 spare [3]; 

} TIFF NEW ONLY, * P TIFF NEW ONLY; 



// false if reading and display; true for saving 



//a pointer pathname of the file 

// sysDdmageXXFilter and sysDcImageFillWindow 

// display size of the tiff image in LUC 
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#define tiffNewFields \ 
objectNewFields \ 
TIFF_NEW_ONLY tiff; 

typedef struct TIFF_NEW { 

tiffNewFields 
} TIFF_NEW, *P_TIFF_NEW; 

resents If imageFlags has the sysDcImageFillWindow flag set, msgNew will pass back the size of the image in 

mils in the rectangle member of the TIFF_NEW struct. 

Status Codes for msgNew 

stsTiffNumStrips returned if the number of strips is bad. 

stsTiflStripByteCount returned if the number of strip byte counts does not match the image length. 

stsTiffStripOffsets returned if there are no strip offsets. 

stsTifHmageTooLarge returned if the image is too large to display (32000 pixels by 32000 pixels). 

StsTiffByteCountZero returned the a byte count is zero. 

stsTiffBadName returned if pName is bad or pNull. 

stsFSNodeNotFound returned the TIFF file is not found. 

and status errors form OSHeapBlockAlloc() 

#define stsTiffNumStrips MakeStatus(clsTiff,0) 

♦define stsTiffStripByteCount MakeStatus(clsTiff,l) 

tdefine stsTiffStripOffsets MakeStatus (clsTiff,2) 

♦define stsTifflmageTooLarge MakeStatus (clsTiff, 3) 

♦define stsTiffByteCountZero MakeStatus (clsTiff, 4) 

♦define stsTiffBadFormatld MakeStatus (clsTiff, 5) 

♦define stsTif fBadName MakeStatus (clsTiff, 6) 

clsPicSeg messages used by clsTiff 



msgPicSegPaintObject 

Paints the Tiff to the drawing context object provided. 

Takes P_PIC_SEG_PAINT_OBJECT, returns STATUS. 

Object Call either msgWinBeginPaint or msgWinBeginRepaint before using this message. A clsPicSeg 
object will send this message to any Tiff object in its display list. If the rectangle in 
P_PIC_SEG_PAINT_OBJECT is all zeros then the whole window is filled with the image. 



clsTiff Messages 



msgTiflPGetMetrics 

Passes back the metrics of the Tiff. 

Takes P_TIFF_METPJCS, returns STATUS. 

♦define msgTiffGetMetrics MakeMsg (clsTiff, 1) 
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msgTiflSetMetrics 

Sets the metrics of the Tiff. 

Takes P_TIFF_METRICS, returns STATUS. 

tdefine msgTiffSetMetrics 

ff Orientation defines 

Valid values for metrics.orientation 



#define tiffOrientTopLeft 
#define tiffOrientTopRight 
#define tiffOrientBottomRight 
#define tiffOrientBottomLeft 
#define tiffOrientLeftTop 
#define tiffOrientRightTop 
#define tiffOrientRightBottom 
tdefine tiffOrientLeftBottom 



MakeMsg(clsTiff, 2) 



<•> 



1 


// 1st 


2 


// 1st 


3 


// 1st 


4 


// 1st 


5 


// 1st 


6 


// 1st 


7 


// 1st 


8 


// 1st 



row top; 1st column left 
row top; 1st column right 
row bottom; 1st column right 
row bottom; 1st column left 
row left; 1st column top 
row right; 1st column top 
row right; 1st column bottom 
row left; 1st column bottom 



Compression types 



Valid values for metrics.compression 

#define tiffCompPackedData 1 
#define tiffCompGroup3 2 
#define tiffCompFax 3 



// 

// only horiz. encoding 

// only horiz. encoding w/EOL 



Rational 



#define tiffCompPackBits 32773 // Mac pack bits run-length 



The ratio of two longs (num / dem). 

typedef struct { 

U32 num; 

U32 dem; 
} RATIONAL, * P RATIONAL; 



Metrics 



The data read from the file tags. 

typedef struct { 

P_U8 pFileName; 
RECT32 rectangle; 



SYSDC 


_IMAGE_FLAGS imageFlags 


U32 


newSubf ileType ; 


// 


U16 


SubfileType; 


// 


U32 


width; 


// 


U32 


length; 


// 


U16 


bitsPerSample; 


// 


U16 


compression; 


// 


U16 


photometriclnterpr 


eta 


U16 


fillOrder; 


// 
// 


P S8 


pDocumentName; 


// 


P S8 


plmageDescription; 


// 


P_S8 


pMake; 


// 


P S8 


pModel; 


// 


P S32 


pStripOffsets; 


// 



// the path for the file 

// the display rect 

//(zero width and height fills the window) 



the tiff data read from the file 
1 the only supported value 
number of pixels in the x dimension 
number of pixels in the y dimension 
number of bits per sample 1, 2, 4 or 8 
the image compression type 
Son; 1 1 0-0 black; highest value white 
111- highest value black; white 
bit order of image bytes 
1 - MSB first; 2 - LSB first 
pointer to a string in a heap or pNull 
pointer to a string in a heap or pNull 
pointer to a string in a heap or pNull 
pointer to a string in a heap or pNull 
pointer to an array of file locations 
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U16 


orientation; 


U16 


samplesPerPixel ; 


S32 


rowsPerStrip; 


P S32 


pStripByteCount s ; 



// see orient tdefines for values 

// number of samples per pixel 

// number of scanlines per strip 

// array of byte counts in each strip 

// x number of samples per resolution unit 

// y number of samples per resolution unit 
planarConf iguration; // 1 the only supported value 

// pointer to a string in a heap or pNull 

// current x position (UNUSED) 

// current y position (UNUSED) 

// only works if 

// 1 for inches; 2 for milimeters 

// page number for the image 

// pointer to a string in a heap or pNull 

// pointer to a string in 

// pointer to a string in 

// pointer to a string in 

// pointer to an array in 



RATIONAL xResolution; 

RATIONAL yResolution; 

U16 

P_S8 pPageName; 

RATIONAL xPosition; 

RATIONAL yPosition; 



U32 group30ptions; 

U16 resolutionUnit; 

U16 pageNumber; 

P_S8 pSoftware; 

P_S8 pDataTime; 

P_S8 pArtist; 

P_S8 pHost Computer; 

P_U16 pColorMap; 



heap or pNull 
heap or pNull 
heap or pNull 
heap or pNull 



} TIFF METRICS, * P TIFF METRICS; 



msgTifiPGetSizeMils 

Provides the actual size of the TIFF image in MILS (1 /1000 inch). 

Takes P_SIZE32, returns STATUS. 

♦define msgTiffGetSizeMils MakeMsg(clsTiff, 3) 



msgTifiBGetSizeMM 

Provides the actual size of the TIFF image in milimeters. 
Takes P_SIZE32, returns STATUS. 



#define msgTiffGetSizeMM 



MakeMsg(clsTiff, 4) 



msgTiflSave 

Saves a TIFF file. 

Takes P_TIFF_SAVE, returns STATUS. 

tdefine msgTiffSave 

// Format of Input image (style. inputDataFormat) 

// The stored data type is provided in the tiff metrics. 



Arguments 



MakeMsg(clsTiff, 5) 



// Curently the only conversion of image compression is 

// from tiffSaveRunLength to tif f CompGroup3 . The data provided for other 

// compression types is writen directly to the file with no conversion. 



tdefine tiffSavePackedData 
tdefine tiffSavePackedBits 
tdefine tiffSaveRunLength 
#define tiffSaveGroup3 



1 //NOT WORKING 

2 //NOT WORKING 

3 // can only be use for a Group 3 Fax file 

4 //NOT WORKING 

// How the image data is provided (style.provideData) 

♦define tiffCallBack 1 // use tif f Save. callback. function () to get row 

tdefine tiffCallObject 2 // not working 

tdefine tiffProvided 3 // all the data is in pBuffer (NOT WORKING) 



typedef struct TIFF_SAVE_STYLE { 
U16 inputDataFormat : 4, 
provideData : 3, 
convert : 1 , 



spare 1 
U16 spare2 



// the compression of the input image data 

// on if the input data is to be converted 
// to metrics. commpresson (NOT WORKING) 



16; 



}TIFF SAVE STYLE, * P TIFF SAVE STYLE; 
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typedef struct TIFF_SAVE * P_TIFF_SAVE; 

typedef STATUS FunctionPtr (P_TIFF_GETROW) (P_TIFF_SAVE pTif fSave) ; 

typedef struct TIFF_SAVE { § 

TIFF_SAVE_STYLE style; £ 

union { % 

P TIFF GETROW function; ° 

OBJECT object; // ObjectCall with msgTiffGetRow ^ 

} callBack; £ 

U32 bufferCount; // number of bytes in pBuffer § 

// if its assumed there is no 5 

// more data and metrics . length 
// will be changed 
P_U8 pBuffer; // provided by the client 

PJJNKNOWN pClientData; // clients own data 

} TIFF_SAVE; 

Comments The TIFF object must be created with the save style (tiff.style.save = true;). The metrics of the TIFF 

must first be set. The default metrics are: 

metrics. newSubfileType = 1; 

metrics . SubfileType = 1; 

metrics. width = 0; 

metrics . length = 0; 

metrics. bit sPerSample = 1; 

metrics. compression = 1; 

metrics. photometriclnterpretation = 0; 

metrics. fillOrder = 1; 

metrics.pDocumentName = pNull; 

metrics.pImageDescription = pNull; 

metrics. pMake = pNull; 

metrics. pModel = pNull; 

metrics . samplesPerPixel = 1; 
metrics. orientation = tiffOrientTopLeft; 
metrics. pStripOff sets = pNull; 
metrics.pStripByteCounts = pNull; 
metrics. rowsPerStrip = 0L; 

metrics.xResolution.num = 0L; // the resolution must be set 

metrics.xResolution.dem = 0L; 

metrics.yResolution.num = 0L; 

metrics. yResolution.dem = 0L; 

metrics. planarConfigurat ion = 1; 

metrics.pPageName = pNull; 

metrics. group30ptions = 0L; 

metrics. resolutionUnit = 2; 

metrics.pageNumber = 0; 

metrics.pSoftware = pNull; 

metrics.pDataTime = pNull; 

metrics. pArtist = pNull; 

metrics.pHostComputer = pNull; 

metrics. pColorMap = pNull; 

All pointers should be alloced on a heap with OSHeapBlockAlloc(). It will save any strings and arrays 
that are not pNull. Strip offsets and strip byte counts are calculated while the image is being saved. 



msgTiffSetGroup3Defaults 

Sets the TIFF metrics to the Group3 compression type 2 defaults. 

Takes P_TIFF_SAVE, returns STATUS. 

#define msgTiffSetGroup3Defaults MakeMsg(clsTiff, 6) 
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iessage 


typedef struct tiff sa\ 


m { 


.rgomenfs 


TIFF_SAVE_STYLE 
union { 


style; 




P TIFF GETROW 


function; 




OBJECT 


object; 




} 


callBack; 




U32 


bufferCount; 



Comments 



P_U8 

P_UNKNOWN 
} TIFF SAVE; 



pBuffer; 
pClientData; 



// ObjectCall with msgTiffGetRow 

// number of bytes in pBuffer 

// if its assumed there is no 

// more data and metrics . length 

// will be changed 

// provided by the client 

// clients own data 



Takes for low resoution and 1 for high resolution. 



msgTiflPGetRow 

Sent client of the TIFF_SAVE to get the next row of the image. 
Takes U32, returns STATUS. 
tdefine msgTiffGetRow 



MakeMsg(clsTiff, 7) 



ReverseBits 

Reverses the bit ordering in each byte in an array of bytes. 
Returns void. 

void EXPORTED ReverseBits ( 

P_U8 pBuf, // the bytes to reverse 

S32 nBytes // the nuber of bytes to reverse 

); 
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Interface to the pop-up tiling routine. 

The functions described in this file are contained in MISC.LIB. 

tifndef TILE_INCLUDED 
fdefine TILE_INCLUDED 

#ifndef GO_INCLUDED 
. tinclude <go.h> 
#endif 

#ifndef GEO_INCLUDED 
#include <geo.h> 
#endif 

typedef enum { 

tileAbove, 

tileBelow, 

tileLeft, 

tileRight 
} TILE LOCATOR; 



// above the target 

// below the target 

//to the left of the target 

//to the right of the target 



TilePopUp 

Center a rectangle under (over/to the left/right o f) another rectangle but staying inside the bounds of a 
third rectangle. 

Returns STATUS. 



Function Prototype 



STATUS PASCAL TilePopUp ( 
TILE_LOCATOR preferred, 
P_RECT32 pPop, 
P_RECT32 pTarget, 
P_RECT32 pWorld 



) 



// preferred location 

// In-Out rect to be manipulated 

// anchor rect 

// surrounding rect, base for pop & target 

// use pNull for theRootWindow 



This routine makes it easy to position pop-up windows next to existingor screen regions. pPop->origin 
is set to the best position tothat rectangle. For example, if you want to center a popup windowa 
selected word but stay inside theRootWindow, you'd set preferredtileBelow, pPop->size to the size 
of the new window, pTarget to thecontaining the selection, and pWorld to pNull. If a window 
ofsize can be centered below pTarget, TilePopUp will return theto insert it at. If it won't fit below, 
but it will fit above,will give THAT position. If it will fit below, but not centered, will sacrifice 
centering to keep it all on screen. 

All rects are assumed to be relative to the same origin. You stillto actually position and insert the actual 
window; this justyou where to put it. 
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This file provides the API's for clsWin, clsWinDev. Two abstract classes, clsDrwCtx and clsPixDev are 
also defined, but they are not used directly by application-level clients. 

clsDrwCtx inherits from clsObject. 

Defines the minimal behavior for a drawing context. 

clsPixDev inherits from clsObject. 

Defines the minimal behavior for a pixelmap graphics device. 

clsWinDev inherits from clsPixDev. 

Provides devices of clsPixDev that can have windows on them. 

clsImgDev inherits from clsWinDev. 

Provides window devices whose pixels are accessible in memory. 

clsWin inherits from clsObject. 

Provides windows onto clsWinDev objects. 

theScreen is a well-known instance of clsWinDev. It is the main display surface for PenPoint. 

theRootWindow is a well-known instance of clsWin. It is the root of the window tree on theScreen. 

Terminology: 

DU4 ~ Device Units, 4th Quadrant. A 4th quadrant coordinate system; device space, device units. This 
is used internally, but not seen by application software. 

LWC ~ Logical Window Coordinates. A 1st quadrant coordinate system. The lower-left-hand corner of 
the window is 0,0. The units are device pixels. These are the coordinates in which windowing operations 
are specified and input is delivered. 

LUC ~ Logical Unit Coordinates. The nature of the coordinate system is determined by a drawing 
context. Such coordinates are always relative to the window. Some drawing contexts will implement 
window messages that takes LWC coordinates and transform them so that window operations can occur 
in LUC space. See sysgraf.h for details. 

Debugging Flags 

The clsWin debugging flag is 'W\ Defined values are: 



flagO (0x0001 

flagl (0x0002; 

flag2 (0x0004; 

flag3 (0x0008 

flag4 (0x0010 

flag5 (0x0020 

flag6 (0x0040 

flag7 (0x0080 



window layout 

window layout 

flash interesting regions during damage 

bitmap caching 

window filing 

font cache char ops 

font cache char ops 

matrix/rectangle math 
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fkg8 (0x0100) layout timing 

flag9 (0x0200) font cache macro ops 

flag 10 (0x0400) msgWinDumpTree outputs input flags 

flagl 1 (0x0800) Measure/Draw text 

flag 1 2 (Ox 1 000) window printing/clipping 

flag 13 (0x2000) unused 

flag 14 (0x4000) unused 

flagl 5 (0x8000) window bitblt coordinates 

tifndef WIN_INCLUDED 
#define WIN_INCLUDED 

#ifndef GO_INCLUDED 

♦include <go.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

♦include <clsmgr.h> 

tendif 

tifndef GEO_INCLUDED 

♦include <geo.h> 

#endif 



JF Typedef s # #defines, and Status Values 



tdefine 
#define 
tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 

tdefine 
tdefine 

tdefine 
tdefine 
tdefine 

typedef 
typedef 
typedef 
typedef 
typedef 



stsWinConstraint 

st sWinHasParent 

stsWinParentBad 

stsWinBad 

stsWinlnfiniteLayout 

stsWinNoEnv 

stsWinlsChild 

stsWinlsDescendant 

stsPixDevBad 

stsPixDevOutOf Regions 

stsWinDevBad 

stsWinDevFull 

stsWinDevCachedHit 



WIN 

DRW_CTX 
PIX_DEV 
WIN_DEV 
IMG DEV 



P_WIN; 
P_DRW_CTX 
P_PIX_DEV 
P_WIN_DEV 
P IMG DEV 



MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 



(clsWin, 
(clsWin, 
(clsWin, 
(clsWin, 
(clsWin, 
(clsWin, 



MakeWarning (clsWin, 
MakeWarning (clsWin, 

MakeStatus (clsPixDev, 
MakeStatus (clsPixDev, 

MakeStatus (clsWinDev, 
MakeStatus (clsWinDev, 
MakeStatus (clsWinDev, 



1) 
3) 
4) 
5) 
6) 
7) 



9) 



1) 
2) 

1) 
2) 
3) 



JF Window style flags 



tdefine wsClipChildren 

tdefine wsClipSiblings 

tdefine wsParentClip 

tdefine wsSaveUnder 

tdefine wsGrowTop 

tdefine wsGrowBottom 

tdefine wsGrowLeft 

tdefine wsGrowRight 

tdefine wsCaptureGeometry 

tdefine wsSendGeometry 

tdefine wsSendOrphaned 



(U32)flag0) 
(U32) flagl) 
(U32)flag2) 
(U32)flag3) 
(U32)flag4) 
(U32)flag5) 
(U32)flag6) 
(U32)flag7) 
(U32)flag8) 
(U32)flag9) 
(U32)flagl0) 



// Don't draw on my children 
// Don't draw on my siblings 
// Borrow my parent's vis rgn 
// Try to save pixels on insert 
// Pixels move to bottom on resize 
// Pixels move to top on resize 
// Pixels move to right on resize 
// Pixels move to left on resize 
// I capture m, s,i,e of children 
// Send me delta, ins, ext advice 
// Send msgOrphaned not msgFree 
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♦define wsSynchRepaint 

♦define wsTransparent 

♦define wsVisible 

♦define wsPaintable 

♦define wsSendFile 

♦define wsShrinkWrapWidth 

♦define wsShrinkWrapHeight 

♦define wsLayoutDirty 

♦define wsCaptureLayout 



♦define wsSendLayout 



((U32)flagl2) 
((U32)flagl3) 
((U32)flagl4) 
((U32)flagl5) 
((U32)flagl6) 

((U32)flagl7) 
((U32)flagl8) 
((U32)flagl9) 
((U32)flag20) 



((U32)flag21) 



// ObjectCall to repaint 

// 

// 

// 

// 



I am transparent 

I am visible 

I can be painted 

I should be filed 



♦define 
♦define 

♦define 

♦define 
♦define 
♦define 
♦define 

♦define 



wsHeightFromWidth 
wsWidthFromHeight 
wsFilelnline 

wsFileNoBounds 
wsFileLayoutDirty 
wsMaskWrapWidth 
wsMas kWr apHe ight 
wsDefault 



((U32)flag22) 
((U32)flag24) 

((U32)flag23) 

((U32)flag26) 
((U32)flag27) 
((U32)flag28) 
((U32)flag29) 
(wsClipChildren 
wsClipSiblings 
wsPaintable 
wsCaptureLayout 
wsSendLayout 
wsLayoutDirty 
wsVisible 
) 



//I shrink to fit children 

// I shrink to fit children 

//My layout is dirty 

// I'm dirty if children delta, 

// extract, insert, or 

// child wsVisible changes 

// I'm dirty if I change size or 

// wsShrinkWrapWidth/Height or 

// wsMaskWrapWidth/Height changes 

// height is computed from width 
// width is computed from height 

// file without object header 

// don't file the bounds 

// always dirty layout bit on restore 

// mask out wsShrinkWrapWidth 

// mask out wsShrinkWrapHeight 

\ 
\ 
\ 
\ 
\ 
\ 
\ 



typedef 
{ 
U32 



struct 



input, 
style; 
} WIN_FLAGS, * P_WIN_FLAGS; 

♦define WinShrinkWrapWidth (style) 
(! ((style) & wsMaskWrapWidth) 



// 
// 



see 
see 



input . h 
ws* flags 



above 



// part of WIN_METRICS 

\ 
&& ((style) & wsShrinkWrapWidth) ) 



\ 



♦define WinShrinkWrapHeight (style) 

(! ((style) & wsMaskWrapHeight) && ((style) & wsShrinkWrapHeight) ) 

♦define WinShrinkWrap (style) \ 

(WinShrinkWrapWidth (style) || WinShrinkWrapHeight (style) ) 

You can use these WinShrinkWrap macros are test if a window has shrink-wrap-width or 
shirnk-wrap-height enabled. If wsMaskWrapWidth/Height is on, the shrink wrapping will be off in 
that dimension. clsGrabBox will turn on wsMaskWrapWidth/Height if the user resizes a window and 
changes the width/height. clsFrame will clear the wsMaskWrapWidth/Height bits and re-layout when 
the user tripple-taps on the title bar. 



Enuml6 (WIN_OPTIONS) 
{ wsPosTop 

wsPosBottom 

wsPosInFront 

wsPosInBack 

wsWinMoved 

wsWinSized 

wsParentMoved 

wsParentSized 

wsLayoutResize 

wsLayoutMinPaint = flagl4, 

wsLayoutNoCache = flag8, 

wsLayoutDefault 
}; 



= 0, 

= flagO, 
= wsPosTop, 
= wsPosBottom, 
= flag9, 
= flaglO, 
= flagl2, 
= flagl3, 
= flagll, 



//In: to msgWinlnsert . 



// Out: 
// Out: 
// Out: 
// Out: 
// In: 
// In: 
// Out: 
= wsLayoutResize // In: 



from msgWinDelta 
from msgWinDelta 
from msgWinDelta 
from msgWinDelta 
to msgWinLayout . . . 
to msgWinLayout . . . 
from msgWinLayout Self 
to msgWinLayout . . . 
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typedef struct 
{ 

WIN parent, 

child; 

RECT32 bounds; 

WIN_DEV device; 

WIN_FLAGS flags; 

TAG tag; 

WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

A P_WIN_METRICS is the argument to most of the messages defined by clsWin. However, for most of 
these messages, not all of the fields are used. In the discussion of each message below, fields which are 
not mentioned are not used; and they don't have to be initialized before sending the message. This is not 
to say that these "unused" fields are not modified during the call; they will be during the processing of 
some messages. 



^Messages Sent to a Window 



msgNew 

Creates a window. 

Takes P_WIN_METRICS, returns STATUS. Category: class message. 

typedef WIN_METRICS WIN_NEW_ONLY, * P_WIN_NEW_ONLY; 
tdefine winNewFields \ 

objectNewFields \ 

WIN_NEW_ONLY win; 

Arguments typedef struct WIN_NEW 

{ 

winNewFields 
} WIN_NEW, *P_WIN_NEW; 

Massage typedef struct 

Arguments { 

WIN parent , 
child; 

RECT32 bounds; 

WIN_DEV device; 

WIN_FLAGS flags; 

TAG tag; 

WIN_OPTIONS options; 
} WINJMETRICS, * P_WIN_METRICS; 

Comments If pArgs->parent is not objNull, clsWin will create the window on the specified parent's window device. 

Note that the new window will not be inserted as a child of the specified parent. You must send 
msgWinlnsert to the new window after creating it to insert it into its parent. 

If pArgs->parent is objNull, the window will be created on pArgs->device. If pArgs->device is objNull, 
clsWin will create the window on OSThisWinDev(). 

Returns 

stsWinParentBad if pArgs->parent is not objNull or a valid window 

stsWinDevBad if pArgs->device is not objNull or a valid window device 

stsWinDevFull if the window device window array can't be grown 

See Als© msgWinlnsert 
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Message 
Arguments 



msgNewDefaults 

Initializes the WIN_NEW structure to default values. 

Takes P_WIN_NEW, returns STATUS. Category: class message. 

typedef struct WIN_NEW 
{ 

winNewFields 
} WIN_NEW, *P_WIN_NEW; 

object. cap |= objCapCall; 

win. parent = objNull; 

win. child = objNull; 

win. device = objNull; 

win. flags. style = wsDefault; 

win . flags . input = 0; 

win. tag = 0; 

win. options = wsPosTop; 

win. bounds. origin. x = 0; 
win. bounds. origin. y = 0; 
win. bounds. size. w = 0; 
win. bounds. size. h = 0; 



msgWinlnsert 

Inserts or changes z-order of a window. 
Takes P_WIN_METRICS, returns STATUS. 
♦define msgWinlnsert 



message 
Arguments 



Comments 



typedef struct 




i 
WIN 


parent , 




child; 


RECT32 


bounds ; 


WIN DEV 


device; 


WIN FLAGS 


flags ; 


TAG 


tag; 


WIN OPTIONS 


options; 


} WIN METRICS, 


* P WIN METRICS; 



MakeMsg (clsWin, 



1) 



You send this message to the child that you want to insert or change z-order. 

In parameters are: 

pArgs->parent = child's new parent or objNull; 
pArgs->options = either wsPosTop or wsPosBottom; 

If pArgs->parent is not objNull or selfs current parent, clsWin will insert self as a child of the specified 
parent. If pArgs->options has wsPosTop on, self will be inserted as the top-most child; if wsPosBottom 
is on, self will be inserted as the bottom-most child. 

If pArgs->parent is objNull or self's current parent, clsWin will change the z-order of self according to 
pArgs->options. If pArgs->options has wsPosTop on, self will be altered in z-space to be the top-most 
child; if wsPosBottom is on, self will be altered to be the bottom-most child. If the z-order of self is 
changed, wsWinMoved will be or-ed into pArgs->options as an out parameter. 

If the receiver's parent has wsCaptureLayout on, wsLayoutDirty will be set on the receiver's parent. 

Returns 

stsWInParentBad if pArgs->parent is not objNull or a valid windowon the same window device 
as self 
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stsWinHasParent if self already has a parent and pArgs->parent is not either objNull or selfs current 
parent 

See Also msgWinlnsertSibling 



Comments 



msgWinlnsertSibling 

Inserts or changes z-order of a window (relative to a sibling). 

Takes P_WIN_METRICS, returns STATUS. 

#define msgWinlnsertSibling MakeMsg(clsWin, 



2) 



Message 


typedef struct 






WIN 


parent, 
child; 




RECT32 


bounds ; 




WIN DEV 


device; 




WIN FLAGS 


flags; 




TAG 


tag; 



See Also 



WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

You send this message to the child that you want to insert or change z-order. This message is similar to 
msgWinlnsert, except pArgs->parent should be the intended sibling of the receiver. 

In parameters are: 

pArgs->parent = receiver's new sibling 
pArgs->options = either wsPosTop or wsPosBottom; 

clsWin will insert self as a sibling of the specified sibling. If pArgs->options has wsPosTop on, self will 
be inserted as in front of pArgs->parent; if wsPosBottom is on, self will be inserted behind 
pArgs->parent. 

If pArgs->parent is already self's sibling, clsWin will change the z-order of self according to 
pArgs->options. If pArgs->options has wsPosTop on, self will be altered in z-space to be in front of 
pArgs->parent; if wsPosBottom is on, self will be altered to be behind pArgs->parent. If the z-order of 
self is changed, wsWinMoved will be or-ed into pArgs->options as an out parameter. 

If the receiver's parent has wsCaptureLayout on, wsLayoutDirty will be set on the receiver's parent. 

Returns 

stsWinParentBad if pArgs->parent is not a valid windowon the same window device as self 

stsWinHasParent if self already has a parent and pArgs->parent isnot a sibling of self 

msgWinlnsert 



msgWinExtract 

Extracts a window from its parent. 

Takes P_WIN_METRICS or pNull, returns STATUS. 

tdefine msgWinExtract MakeMsg (clsWin, 3) 

Comments If a P_WIN_METRICS is passed instead of pNull the same information returned by msgWinGetMetrics 

is returned in the WIN.METRICS structure. This will include the parent field BEFORE the extract is 
performed. If the window is already extracted, stsWinParentBad is returned, and any passed 
WIN_METRICS field is unmodified. 

If the receiver's parent has wsCaptureLayout on, wsLayoutDirty will be set on the receiver's parent. 
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msgWinDelta 

Moves and/or resizes a window. pArgs->bounds should be the newly desired bounds (size AND 
position). 

Takes P_WIN_METRICS, returns STATUS. 

♦define msgWinDelta MakeMsg(clsWin, 4) 



Message 


typedef struct 




Arguments 


{ 






WIN 


parent, 
child; 




RECT32 


bounds; 




WIN_DEV 


device; 




WIN_FLAGS 


flags; 




TAG 


tag; 




WIN_OPTIONS 


options; 



} WIN_METRICS, * P_WIN_METRICS; 

Comments If the receiver is involved in a layout episode (msgWinLayout is being processed in the receiver's 

window tree), the new bounds will be remembered for use at the end of the layout episode. If the new 
bounds has a new width or height, and a cached desired size is being remembered for the receiver, the 
desired size will be discarded if either of the following is true: 

♦ the new bounds has a new width and the receiver has wsHeightFromWidth on or does not have 
wsShrinkWrapWidth on 

♦ the new bounds has a new height and the receiver has wsWidthFromHeight on or does not have 
wsShrinkWrapHeight 

If the receiver is involved in a layout episode this is all that is done and stsOK is returned. 

If the receiver's parent has wsCaptureGeometry on, the parent will be sent msgWinDeltaOK. If the 
parent responds with anything other than stsOK, that status will be returned and nothing else is done. 
Otherwise, the (possibly modified) bounds returned by the parent will be used. If the parent modified 
the proposed child origin, wsParentMoved will be or-ed into pArgs->options as an out parameter. If the 
parent modified the proposed child size, wsParentSized will be or-ed into pArgs->options as an out 
parameter. 

If the receiver is visible and paintable (wsVisible and wsPaintable are on for the receiver and all of its 
ancestors), valid portions of the receiver's window may be copied to their new location to avoid damage 
and repaint of those portions. 

If the receiver has any of the grow bits on (wsGrowBottom/Top/Left/Right), the appropriate grow 
semantics will be applied to determine how to move the receiver's children and what portions of the 
receiver's window to damage for subsequent repaint. 

If pArgs->bounds is a new bounds and the receiver's parent has wsCaptureLayout on, wsLayoutDirty 
will be set on the receiver s parent. 

If pArgs->bounds.size is a new size and the receiver has wsSendLayout on, wsLayoutDirty will be set on 
the receiver. 

Subclasses that want to know when their position or size has changed should not expect that 
msgWinDelta is the only way for this to happen. If you need to know this information, you should turn 
on wsSendGeometry and catch msgWinMoved or msgWinSized. clsWin may change a window's 
bounds without sending msgWinDelta to the window. 
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msgWinLayout 

Tells a window sub-tree to layout. 
Takes P_WIN_METRICS, returns STATUS. 





fdefine msgWinLayout MakeMsg(clsWin, 


Message 


typedef struct 




Arguments 


{ 






WIN 


parent , 
child; 




RECT32 


bounds ; 




WIN DEV 


device; 




WIN FLAGS 


flags; 




TAG 


tag; 




WIN OPTIONS 


options; 




} WIN_METRICS, 


* P_WIN_METRICS; 


Comments 


You should send 


1 msgWinLayout to a window after you have alte 



41) 



bounds or its descendants bounds must be recomputed. 

For example, if you create an instance of clsTableLayout (a subclass that lays out its children in rows and 
columns) and insert children into it, you must send msgWinLayout to the table layout window to force 
it to "layout" itself and its children. 

After msgWinLayout has been sent, every window in the receiver's tree will be positioned and sized as 
required. You can then use msgWinlnsert to insert the root of the tree on the display and allow the 
windows to paint. 

In parameters: 

bounds = new final bounds for receiver if wsLayoutResize is not 

on in pArgs->options 

options = wsLayoutDefault, 0, or any combination of wsLayoutResize, 

wsLayoutMinPaint 

Subclasses must not catch msgWinLayout. clsWin will respond by beginning a "layout episode" during 
which the windows in the receiver's tree will be layed out. 

The algorithm for a layout episode is as follows: 

for the receiver and each of its descendants 
If the window has wsLayoutDirty on 

If the bounds of the window have been fixed by a previous 
msgWinDelta during the layout episode 

send the window msgWinLayoutSelf with the following 
WIN_METRICS parameters: 

bounds. size = current bounds. size; 
options = 0; 

Otherwise, 

send the window msgWinLayoutSelf with the following 
WIN_METRICS parameters: 

options = wsLayoutResize; 

copy back WINJMETRICS. bounds. size as the new size for the 
window . 

If the window' s parent has wsLayoutDirty on, switch to the 
window's parent and continue down the tree from there. 

After the entire tree has been traversed, traverse the tree again and 
process wsCaptureGeometry and wsSendGeometry requests as follows: 



WIN.H 303 

Messages Sent to a Window 

For each window 

If the origin or size has changed 53 

If the window's parent has wsCaptureGeometry on I 

send msgWinDeltaOK to the window's parent; < 

O 

If the window has wsSendGeometry on °* 

send msgWinMoved and/or msgWinSized to the window. ^ 

O 

a 
After the geometry notifications have been done, apply all of the new Z 

bounds for each window in the tree as in msgWinDelta. 

If wsLayoutResize is NOT set in pArgs->options, then you must set pArgs->bounds to the new 
rectangle that the receiver must fit into ~ it will lay out accordingly; otherwise the receiver will lay out to 
its desired size. 

If wsLayoutMinPaint is not on, window damage will not be computed during the layout episode — all 
of the windows in the window tree will be damaged and repaint after the layout episode. This will result 
in faster layout, at the expense of some (possibly) unneccessary repaints. If wsLayoutMinPaint is on, the 
true damaged area will be computed. This may take longer, but will result in the minimal amount of 
repaint after the layout episode. 

In general this message should not be handled by subclasses. However, it results in the sending of 
msgWinLayoutSelf, which does need to be handled by subclasses. 

Returns 

stsWinlnfiniteLayout the layout episode does not appear to terminate 

See Also msgWinLayoutSelf 



Arguments 



msgWinLayoutSelf 

Tells a window to layout its children (sent during layout). 

Takes P_WIN_METRICS, returns STATUS. 

#define msgWinLayoutSelf MakeMsg(clsWin, 42) 



typedef struct 




i 

WIN 


parent, 




child; 


RECT32 


bounds ; 


WIN_DEV 


device; 


WINJFLAGS 


flags; 


TAG 


tag; 


WIN_OPTIONS 


options; 


} WIN METRICS, 


* P WIN METRICS; 



:®mmemt% This message is sent by clsWin during a layout episode. It can be handled by knowledgeable window 

classes. 

When sent, pArgs->bounds.size contains the present size. If pArgs->options is then the window 
cannot change pArgs->bounds.size, it must lay out its children, as best it can, within those bounds. If 
pArgs->option is wsLayoutResize then it may change pArgs->bounds.size to its desired size. 

After pArgs->bounds.size is determined, the window should msgWinDelta each child to its final 
position and size. 

In order to determine its desired size and layout, a window may need to send msgWinGetDesiredSize to 
some, or all, of its children first. 
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clsWin responds to msgWinLayoutSelf by doing nothing and returning the current window size in 
pArgs->bounds.size if wsLayoutResize is on in pArgs->options. 

See Also msgWinLayout 

msgWinGetDesiredSize 

Gets the desired size of a window (sent during layout). 

Takes P_WIN_METRICS, returns STATUS. 

tdefine msgWinGetDesiredSize MakeMsg(clsWin, 43) 

Messoge typedef struct 

Arguments { 

WIN parent, 

child; 

RECT32 bounds; 

WIN_DEV device; 

WIN_FLAGS flags; 

TAG tag; 

WIN_OPTIONS options; 

} WIN_METRICS, * P_WIN_METRICS; 

Comments This message should not be handled by a subclass. 

If the receiver is not in a layout episode, clsWin responds by returning the receivers current bounds. 

Otherwise, if the desired size has already been computed (cached) for the receiver, that value will be 
returned. 

Otherwise, msgWinLayoutSelf will be self-sent with the following WINJMETRICS parameters: 

options = wsLayoutResize; 

Subclasses should catch msgWinLayoutSelf, layout to their desired size and return the desired size in 
WIN_METRICS.bounds.size. The computed desired size will be remembered in the windows cache for 
future use and will be passed back in pArgs->bounds.size. 

See Also msgWinLayout 

msgWinGetBaseline 

Gets the desired x,y alignment of a window. 
Takes P_WIN_METRICS, returns STATUS. 

♦define msgWinGetBaseline MakeMsg (clsWin, 46) 

tdefine wsNoXBaseline ((U16)flag0) 
tdefine wsNoYBaseline ((Ul6)flagl) 

Message typedef struct 

Arguments { 

WIN parent, 
child; 

RECT32 bounds; 

WIN_DEV device; 

WIN_FLAGS flags; 

TAG tag; 

WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

Comments Subclasses can set pArgs->bounds.origin to reflect the window's desired baseline position. clsWin will set 

both x and y to 0,0. 



Comments 
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pArgs->bounds.size should contain the size of the window. This is useful for windows whose alignment 
is a function of window size (like centered). 

If the receiver does not have either an x or y baseline, wsNoXBaseline and/or wsNoYBaseline can be 
or-ed into pArgs->options as an out parameter. 

clsWin will always set pArgs->options to wsNoXBaseline I wsNoYBaseline (i.e. the default is the 
window has no x or y baseline). 

msgWinSetLayoutDirty 

Turns wsLayoutDirty bit on or off, returns previous value. 

Takes BOOLEAN, returns BOOLEAN. 

#define msgWinSetLayoutDirty MakeMsg(clsWin, 44) 

If the window has a cached desired size, and wsLayoutDirty comes on, the desired size will be discarded. 



msgWinSetLayoutDirtyRecursive 

Turns wsLayoutDirty bit on for every window in subtree. 

Takes BOOLEAN, returns nothing. 

#define msgWinSetLayoutDirtyRecursive MakeMsg (clsWin, 
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Comments 



msgWinSend 

Sends a message up a window ancestry chain. 
Takes P_WIN_SEND, returns STATUS. 
#define msgWinSend 



MakeMsg(clsWin, 36) 



Enuml6 (WIN_SEND_FLAGS) 
{ wsSendDefault = 0, 

wsSendlntraProcess = flagO, 
}; 

typedef struct 
{ 



// stop at process transition 



U32 



lenSend; 



// length of message, 

// SizeOf (WIN_SEND) minimum 

// 

// the "message" 

// an argument to the message 



WIN_SEND_FLAGS flags; 
MESSAGE msg; 
P_UNKN0WN data [II; 
// clients can put 
// more data here 
// if needed 
} WIN_SEND, * P_WIN_SEND; 

The receiver may reply to the message or forward the message up the window parent chain. clsWin will 
forward the message to the parent using ObjectSendUpdate. If the message reaches the root window 
stsMessagelgnored is returned. If the wsSendlntraProcess flag is true the message will not be 
propagated past a process transition (based on the owner of the window object); in this case 
stsMessagelgnored may also be returned. 

lenSend must be at least SizeOf(WIN_SEND) but may be larger to move more data to a window owned 
by another process. A single unit of data, data[0] is defined in WIN_SEND as a convenience. The message 
a window receives when msgWinSend is forwarded is msgWinSend, NOT msg. The field msg is 
provided so the receiving client can properly interpret the purpose of the msgWinSend. 
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msgWinGetMetrics 

Gets full window metrics. 

Takes P_WIN_METRICS, returns STATUS. 

tdefine msgWinGetMetrics MakeMsg(clsWin, 5) 



typedef struct 




i 
WIN 


parent , 




child; 


RECT32 


bounds; 


WIN DEV 


device; 


WIN FLAGS 


flags ; 


TAG 


tag; 


WIN OPTIONS 


options; 


} WIN METRICS, 


* P WIN METRICS; 



Comments pArgs->parent passes back the receiver's parent pArgs->child passes back self pArgs->bounds passes back 

size and parent relative position pArgs->device passes back self's device pArgs->flags passes back self's 
window and input flags pArgs->tag passes back sel f s tag 

msgWinGetFlags 

Like msgWinGetMetrics but passes back flags only. 
Takes P_WIN_METRICS, returns STATUS. 

#define msgWinGetFlags MakeMsg(clsWin, 6) 



typedef struct 
{ 
WIN 




parent, 




child; 


RECT32 


bounds ; 


WIN DEV 


device; 


WIN FLAGS 


flags; 


TAG 


tag; 


WIN OPTIONS 


options; 


} WIN METRICS, 


* P WIN METRICS; 



pArgs->flags passes back self's window and input flags. 



msgWinSetFlags 

Sets the window flags. 

Takes P_WIN_METRICS, returns STATUS. 

#define msgWinSetFlags MakeMsg(clsWin, 7) 



typedef struct 
i 




I 
WIN 


parent , 




child; 


RECT32 


bounds ; 


WIN DEV 


device; 


WIN FLAGS 


flags ; 


TAG 


tag; 


WIN OPTIONS 


options; 


} WIN METRICS, 


* P WIN METRICS; 



pArgs->flags should be set to the new window and input flags. 
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If wsVisible is changed and the receiver's parent has wsCaptureLayout on, wsLayoutDirty will be set on 

the receiver's parent. w, 

If the new flags result in a new value for WinShrinkWrapO (e.g. wsShrinkWrapWidth changes) and the IE 

receiver has wsSendLayout on, wsLayoutDirty will be set on the receiver. g 

<* 

mmmmmmmmmmMmmmmmmmmmmMmmmmmmMmmmmmmmmmmmMmmmmmM^ W) 

msgWInGetTag o 

Like msgWinGetMetrics but passes back tag only. S 

Takes P_WIN_METRICS, returns stsOK. 

#define msgWinGetTag MakeMsg(clsWin, 37) 



Message typedef struct 

Arguments { 



WIN 


parent , 




child; 


RECT32 


bounds ; 


WIN_DEV 


device; 


WIN_FLAGS 


flags ; 


TAG 


tag; 


WIN_OPTIONS 


options; 


} WIN METRICS, 


* P WIN_METRICS; 



Comments pArgs->tag passes back self's tag. 



msgWinSetTag 

Sets the window tag. 

Takes P_WIN_METRICS, returns STATUS. 

tdefine msgWinSetTag MakeMsg(clsWin, 38) 



Message typedef struct 

Argwments { 



WIN 


parent , 




child; 


RECT32 


bounds ; 


WIN_DEV 


device; 


WINJLAGS 


flags ; 


TAG 


tag; 


WIN_OPTIONS 


options; 


} WIN METRICS, 


* P_WIN_METRICS; 



>mments pArgs->tag should be set to the new window tag. 

msgWinlsVisible 

Returns stsOK if the receiver and all its ancestors have wsVisible on. 

Takes nothing, returns STATUS. 

#define msgWinlsVisible MakeMsg(clsWin, 40) 

Comments clsWin will traverse the parent chain of the receiver until the parent is objNull or the root window of 

the receiver's device. If the receiver or any of its ancestors have wsVisible off in their window flags, 
stsFailed is returned. Otherwise, if the final ancestor is the root window on the receiver's device, stsOK 
is returned. 
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msgWinlsDescendant 

Checks if pArgs->child is a descendant of the receiver. 

Takes P_WIN_METRICS, returns STATUS. 

tdefine msgWinlsDescendant MakeMsg(clsWin, 59) 

Message typedef struct 

Arguments { 

WIN parent , 
child; 

RECT32 bounds; 

WIN_DEV device; 

WIN_FLAGS flags; 

TAG tag; 

WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

In parameters child: child to look for options: for direct children, wsEnumRecursive for 
recursive or-in wsEnumSelf to include self in the search 

clsWin will check the receiver's children and return stsWinlsChild if pArgs->child is one of them. 

If pArgs->options has wsEnumRecursive on, the search will continue down the window tree until 
pArgs->child is found or all of the receiver's descendants have been examined. If no match is found, 
stsNoMatch is returned. 

If pArgs->child is self and wsEnumSelf is on in pArgs->options, stsWinlsChild is returned; otherwise 
stsNoMatch is returned. 

Returns Value 

stsWinlsChild if pArgs->child is self or a direct child 

stsWinlsDescendant if pArgs->child is a descendant 

stsNoMatch if pArgs->child is not a descendant 

msgWinGetPopup 

Gets the popup window. 

Takes P_WIN_METRICS, returns stsOK. 

tdefine msgWinGetPopup MakeMsg(clsWin, 53) 

Message typedef struct 

Arguments { 

WIN parent, 
child; 

RECT32 bounds; 

WIN_DEV device; 

WIN_FLAGS flags; 

TAG tag; 

WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

Comments pArgs->child passes back self's popup window. 

The popup window is traversed during msgWinFindTag only. See msgWInFindTag for more details. 
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Message 
Arguments 



msgWinSetPopup 

Sets a popup window. 

Takes P_WIN_METRICS, returns STATUS. 

#define msgWinSetPopup 
typedef struct 



MakeMsg(clsWin, 54) 



WIN 


parent, 




child; 


RECT32 


bounds ; 


WIN DEV 


device; 


WIN FLAGS 


flags; 


TAG 


tag; 



WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

Comments pArgs->child should be set to the popup window. 

The popup window is traversed during msgWinFindTag only. See msgWinFindTag for more details. 

One example of popup window use is in clsMenuButton. A menu button will set its popup window to 
be its menu. This allows you to use msgWinFindTag on a menu bar and find a menu button in one of 
the popup menus. 



Comments 



msgWinFindAncestorTag 

Searches for a match on argument tag. Returns match or objNull. 

Takes U32, returns OBJECT. 

tdefine msgWinFindAncestorTag MakeMsg(clsWin, 49) 

The search is up the ancestor chain; the first match found is returned. If no match is found, objNull is 
returned. 



msgWinFindTag 

Searches for a match on argument tag. Returns match or objNull. 

Takes U32, returns OBJECT. 

tdefine msgWinFindTag MakeMsg(clsWin, 39) 

Comments The search is breadth first; but, it starts with the first child of the window, not the window itself. The 

first match found is returned. If no match is found, objNull is returned. Trees rooted at popup windows 
(set with msgWinSetPopup) are traversed too. The traversal order is siblings first, then children, then 
popups. 

msgWinSetVisible 

Turns window visibility bit on or off, returns previous value. 

Takes BOOLEAN, returns BOOLEAN. 

#define msgWinSetVisible MakeMsg(clsWin, 8) 

Comments If visibility is changed and the receiver's parent has wsCaptureLayout on, wsLayoutDirty will be set on 

the receiver's parent. 
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msgWinSetPaintable 

Turns window paintability bit on or off, returns previous value. 

Takes BOOLEAN, returns BOOLEAN. 

tdefine msgWinSetPaintable MakeMsg(clsWin, 9) 



msgWinBeginRepaint 

Sets up window for painting on "dirty" region. 

Takes P_RECT32 or pNull, returns STATUS. 

tdefine msgWinBeginRepaint MakeMsg(clsWin, 10) 

Comments A BeginRepaint/EndRepaint pair bracket an update episode for a window. They should be sent ONLY 

in response to the receipt of msgWinRepaint. If pArgs is not pNull a rectangle describing the bounds of 
the dirty region is passed back. 



msgWinEndRepaint 

Tells window system that repainting has ended for this window. 

Takes nothing, returns STATUS. 

♦define msgWinEndRepaint MakeMsg(clsWin, 11) 



msgWinBeginPaint 

Sets up window for painting on its visible region. 

Takes P_RECT32 or pNull, returns STATUS. 

tdefine msgWinBeginPaint MakeMsg(clsWin, 12) 

:©mments A BeginPaint/EndPaint pair can be used to paint on a window at anytime, even if it is not dirty. If pArgs 

is not pNull a rectangle describing the bounds of the visible region is passed back. 



msgWinEndPaint 

Tells window system that painting has ended for this window. 

Takes nothing, returns STATUS. 

tdefine msgWinEndPaint MakeMsg(clsWin, 13) 



msgWinDirtyRect 

Marks all or part of a window dirty. 

Takes P_RECT32 or pNull, returns STATUS. 

tdefine msgWinDirtyRect MakeMsg(clsWin, 14) 

If pNull is passed the entire window is marked dirty. If the dirty part is visible, the window will 
eventually receive msgWinRepaint as a side effect of this message. 
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msgWInUpdate 

Forces a window to repaint now, provided that it needs repainting. 

Takes nothing, returns STATUS. 

♦define msgWinUpdate MakeMsg(clsWin, 35) 

Comments The window and all its descendants that need painting are sent msgWinRepaint. However, only 

windows owned by the current subtask are processed. 



msgWinCleanRect 

Marks all or part of a window clean. 

Takes P_RECT32 or pNull, returns STATUS. 

♦define msgWinCleanRect MakeMsg(clsWin, 15) 

Comments If pNull is passed the entire window is marked clean. In general it is not a good idea to mark a window 

clean. Window activity is asynchronous and application software has no way of knowing if the window 
is really clean. 



Arguments 



Comments 



msgWinCopyRect 

Copies pixels within a window. 

Takes P_WIN_COPY_RECT, returns STATUS. 

♦define msgWinCopyRect 



MakeMsg(clsWin, 16) 



Enuml6 (WIN_COPY_FLAGS) 

{ wsCopyNormal = 0, 

wsPlanePen = flagO, 

wsPlaneMask = flagl, 

wsSrcNotDirty = flag2, 

wsDstNotDirty = flag3, 

wsChildrenStay = flag4, 

wsCopyRelative = flag5, 

}; 

typedef struct 

{ 



// normal copy of normal planes 

//do pen plane (s) too 

// use planeMask 

// don't mark source dirty 

// don't mark dirty dst pixels dirty 

// xy is a delta on srcRect. origin 



RECT32 srcRect; 


// rectangle in LWC 


XY32 xy; 


// new location in LWC 


WIN COPY FLAGS flags; 




U16 planeMask; 





} WIN_COPY_RECT, * P_WIN_COPY_RECT; 

In general, pixels which are dirty, invisble, or just off the edge of the window, are not copied. Rather, at 
the destination it is recognized that they did not get copied, and they are marked dirty instead. Also, it is 
assumed that pixels at the source need to be repainted. (This behavior is controlled by the two flags 
wsSrcNotDirty and wsDstNotDirty). 

The intent of this message is that it be used as an accelerator; to move potentially good pixels to a new 
location. It should be sent OUTSIDE of an update episode. Then, areas that require repainting will be 
marked dirty and handled by the next update episode. 

If, by mistake, this message is sent inside an update episode it will probably not copy any pixels, because 
it will assume that all the pixels that are currently being updated are dirty. 



312 PENPOINT API REFERENCE 

Part 3 / Windows and Graphics 

The use of wsCopyNormal is recommended to copy the normal planes and skip the pen plane(s). More 
precise control over which planes are copied is available with the use of flags wsCopyNormal, 
wsPlanePen and wsPlaneMask (in conjunction with the planeMask field). 

If wsChildrenStay is not in in pArgs->flags and the receiver has children in the area being copied, the 
children will be moved also. Note that even if the receiver has wsCaptureGeometry on, the receiver will 
not be sent msgWinDeltaOK when the children are moved. However, each child that has 
wsSendGeometry on and is moved will be sent msgWinMoved. 



Messoge 
Argument 



Comments 



msgWinTransformBounds 



Transforms bounds from receiver's to another window's LWC. 
Takes P_WIN_METRICS, returns STATUS. 

#define msgWinTransformBounds MakeMsg(clsWin, 
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typedef struct 
{ 



WIN 

RECT32 
WIN_DEV 
WIN_FLAGS 
TAG 



parent , 

child; 

bounds ; 

device; 

flags; 

tag; 



WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

Set the pArgs->parent to a window or use objNull for the receiver's actual parent. pArgs->bounds in the 
receiver's LWC are transformed into the equivalent bounds in the parent's LWC. 



msgWinEnum 

Enumerate a window's children. 
Takes P_WIN_ENUM, returns STATUS. 

#define msgWinEnum 



Enuml6 (WIN_ENUM_FLAGS) 
{ wsEnumChildren = 0, 
wsEnumSelf = flagO, 
wsEnumRecursive = flagl, 
wsEnumFlags = flag2, 
wsEnumBreadthFirst = flag3, 
wsEnumSendFile = flag4, 



wsEnumMetrics 
}; 

typedef struct 
{ 

U16 



P_WIN 

P WIN FLAGS 



U16 



max, 
count ; 



pWin; 
pFlags; 



next ; 



WIN_ENUM_FLAGS flags; 
} WIN ENUM, * P WIN ENUM; 



MakeMsg(clsWin, 33) 



// enum children only 

// enum self too 

// enum children of children... 

// return flags too 

// 



// enum only windows with 
// wsSendFile == TRUE 
= flag5 // return WIN METRICS 



// in = size of pWin[] and pFlags[] arrays 
// in = # to return in arrays 
//if count > max then memory may be allocated 
// out = # of valid entries in arrays 

// in = ptr to arrays 

// out = if memory was allocated 

// client should free the memory 

//in = to start at beginning 

// OR previous out value to pick up 

// where we left off 

// in = see options 
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Comments Here is some sample code for enumerating the direct children of a window: 

WIN_ENUM e; g 

WIN w[10]; I 

U16 i; < 

e.max = 10; // e.pWin is an array of 10 WINs © 

e. count = maxU16; //' allocate as much storage as needed °* 

e.pWin = w; // put windows in w array 5 

e. flags = wsEnumChildren; // return only direct children O 

e.next =0; // start from the first child Z 

s = ObjectCall (msgWinEnum, parent, &e) ; 

// stsEndOfData means we got them all 
if (s == stsEndOfData) 
s = stsOK; 

// e. count is the actual number of children 
for (i =0; i < e. count; i++) { 
child = e.pWinfi]; 

// put code that does something with 

// child here 
} 

// free any allocated storage 
if (e.pWin != w) 

StsWarn (OSHeapBlockFree (e .pWin) ) ; 

If you want to retrieve all of the window metrics for each window, turn on wsEnumMetrics in 
pArgs->flags and set pArgs->pWin to an array of WIN_METRICS structs. 

Returns 

StsEndOfData if all of the descendants have been returned 

See Also WinEachChild 

—_ ^^^ — " — - — — — — — 

Helper macro for enumerating the direct children of a window 
Returns nothing. 

♦define WinEachChild (parent, child, s) \ 

{ \ 

WIN_ENUM _e; \ 

WIN _w[10]; \ 

U16 _i; \ 

\ 
_e.max =10; \ 

_e. count = maxU16; \ 

_e.pWin = _w; \ 

_e. flags = wsEnumChildren; \ 

_e.next =0; \ 

\ 
s = ObjectCall (msgWinEnum, parent, &_e) ; \ 

\ 

if (s == stsEndOfData) \ 

s = StsOK; \ 

\ 
for (_i = 0; _i < _e. count; _i++) \ 

{ \ 

child = _e.pWin[_i]; 
// put code that does something with 
// child here 

Comments You can use WinEachChild to retrieve the direct children of a window. 

See Also WinEndEachChild 
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WinEndEachChild 

Ending helper macro for most common window enumeration idiom. 
Returns nothing. 

♦define WinEndEachChild \ 

} /* for */ \ 

if (_e.pWin != (P_WIN)_w) \ 

OSHeapBlockFree (_e . pWin) ; \ 
} // end scope 

WinEachChild and WinEndEachChild 

Use WinEachChild(parent,child,status) to start a for loop enumeration of the children of parent. The 
variable child will be set for each child. Close the enumeration with WinEndEachChild. Here is an 
example; notice that semicolons are NOT used. 

WinEachChild(p,c,s)// send a message to c // break if necessary 
// s is set here 

The code placed between these macros becomes the body of a for loop. If it is necessary to exit the loop 
early, use a break statement, not a return or goto, so that WinEndEachChild is reached. If an error in 
the enum occurs, the for loop will not be executed, and the status value will be set. 

msgWinRepaint 

Tells a window to repaint itself. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

#define msgWinRepaint MakeMsg(clsWin, 21) 

Comments Windows only receive this if the wsPaintable flag is true. This message is sent by the window system 

during an update episode. It should NOT be sent by the application. 

If you want a window to be updated immediately (synchronously), use msgWinUpdate. 

Upon receipt of this message, applications should NOT perform other windowing operations that are 
visually significant (msgWinDelta, msgWinlnsert, msgWinExtract, etc.). When this message is 
received; it is too late. The only thing that should happen is repainting. 

See Also msgWinBeginRepaint 

Tells a window its parent has been freed. 
Takes nothing, returns STATUS. Category: advisory message, 
♦define msgWinOrphaned MakeMsg(clsWin, 22) 

Comments Windows only receive this if the wsSendOrphaned flag is true. 

msgWinlnsertOK 

Informs a potential parent of a pending child insertion. 

Takes P_WIN_METRICS, returns STATUS. Category: advisory message. 

♦define msgWinlnsertOK MakeMsg(clsWin, 23) 
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Message 


typedef struct 




Arguments 


{ 






WIN 


parent , 
child; 




RECT32 


bounds ; 




WIN DEV 


device; 




WIN FLAGS 


flags; 




TAG 


tag; 




WIN OPTIONS 


options; 




} WIN_METRICS, 


* P_WIN_METRICS; 


Comments 


pAres->child is 


the window that is 



pArgs->child is the window that is being inserted; pArgs->bounds is its bounds, which the parent can 
modify. If receiver does not return stsOK the insertion will be denied. 

Windows only receive this if wsCaptureGeometry in flags is true. 



Messoge 
Arguments 



Comments 



msgWinExtractOK 

Informs parent of a pending child extraction. 

Takes P_WIN_METRICS, returns STATUS. Category: advisory message. 

♦define msgWinExtractOK MakeMsg(clsWin, 24) 



typedef struct 
{ 



WIN 

RECT32 
WIN_DEV 
WIN_FLAGS 
TAG 



parent , 

child; 

bounds; 

device; 

flags; 

tag; 



WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

pArgs->child is the window that is being extracted. If receiver does not return stsOK the extraction will 
be denied. 

Windows only receive this if wsCaptureGeometry in flags is true. 



yrgwmersts 



Comments 



msgWinDeltaOK 

Informs parent of a pending change in a child window's size or position. 
Takes P_WIN_METRICS, returns STATUS. Category: advisory message. 
#define msgWinDeltaOK MakeMsg(clsWin, 25) 



typedef struct 




WIN 


parent, 




child; 


RECT32 


bounds ; 


WIN DEV 


device- 


WIN FLAGS 


flags; 


TAG 


tag; 



WIN_OPTIONS options; 
} WIN_METRICS, * P_WIN_METRICS; 

pArgs are the arguments to msgWinDelta. If receiver does not return stsOK the delta will be denied. 

Windows only receive this if wsCaptureGeometry in flags is true. 
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msgWinFreeOK 

Informs parent of the pending destruction of a child window. 
Takes WIN, returns STATUS. Category: advisory message. 
#define msgWinFreeOK MakeMsg(clsWin, 26) 

Comments Windows only receive this if wsCaptureGeometry in flags is true. 

msgWinlnserted 

Advises window that it has been inserted. 

Takes WIN, returns STATUS. Category: advisory message. 

tdefine msgWinlnserted MakeMsg(clsWin, 27) 

Comments pArgs is the window that actually was inserted, it may be self or an ancestor. If it is an ancestor, the 

window is being inserted indirectly, as part of a sub-tree insertion. 

Windows only receive this if wsSendGeometry in flags is true. 



msgWinExtracted 

Advises window that it has been extracted. 

Takes WIN, returns STATUS. Category: advisory message. 

#define msgWinExtracted MakeMsg(clsWin, 28) 

:®mm®m& pArgs is the window that actually was extracted, it may be self or an ancestor. If it is an ancestor, the 

window is being extracted indirectly, as part of a sub-tree extraction. 

Windows only receive this if wsSendGeometry in flags is true. 

msgWinVisibilityChanged 

Advises window that its visibility may have changed. 

Takes WIN, returns STATUS. Category: advisory message. 

tdefine msgWinVisibilityChanged MakeMsg(clsWin, 60) 

pArgs is the window that actually was changed, it may be self or an ancestor. If it is an ancestor, the 
window is being made visible or invisible indirectly, as part of a sub-tree insertion or extraction. 

Note that if pArgs is an ancestor, the ancestor's visibility change may not have changed self's visibility. 
Use msgWinlsVisible to determine self's current visibility. 

Windows only receive this if wsSendGeometry in flags is true. 

msgWinlsVisible 

msgWinMoved 

Advises window that it, or an ancestor, has moved. 

Takes P_WIN_METRICS, returns STATUS. Category: advisory message. 

tdefine msgWinMoved MakeMsg(clsWin, 29) 
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Message 
Arguments 



Comments 



typedef struct 




t 
WIN 


parent , 




child; 


RECT32 


bounds; 


WIN DEV 


device; 


WIN FLAGS 


flags ; 


TAG 


tag; 


WIN OPTIONS 


options; 


} WIN METRICS, 


* P WIN METRICS; 



Windows only receive this if wsSendGeometry in flags is true. pArgs->bounds. origin is the previous 
position. pArgs->child is the window that actually moved, it may be self or an ancestor. If it is an 
ancestor, the window is being moved indirectly, as part of a sub-tree move. 



msgWinSized 

Advises window that it, or an ancestor, has changed size. 

Takes P_WIN_METRICS, returns STATUS. Category: advisory message. 

#define msgWinSized MakeMsg(clsWin, 30) 



Message 


typedef struct 




Arguments 


{ 






WIN 


parent , 
child; 




RECT32 


bounds; 




WIN DEV 


device; 




WIN FLAGS 


flags ; 




TAG 


tag; 




WIN OPTIONS 


options; 




} WIN_METRICS, 


* P WIN METRICS; 


Comments 


Windows only receive this if wsSen 



pArgs->child is the window that actually changed size, it may be self or an ancestor. If it is an ancestor, 
the window did not actually change size, the ancestor did. 

msgWinStartPage 

Advises window that it is on a printer, and printing is about to commence. 

Takes pNull, returns STATUS. Category: advisory message. 

#define msgWinStartPage MakeMsg(clsWin, 48) 

Comments clsWin does nothing and returns stsOK in response to this message. 

This message is sent before a page is about to be printed. The window may want to set a state variable 
used to change the way the window paints on a printer. 



msgWinSort 

Sorts a window's children into a back to front order determined by a client supplied comparison 
function. 



Takes P_WIN_SORT, returns STATUS. 
♦define msgWinSort 



MakeMsg(clsWin, 52) 
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Function Prototype 



Comments 



typedef struct 
{ 

P_WIN_SORT_PROC pSortProc; 

PJJNKNOWN pClientData; 

BOOLEAN changed; 

} WIN SORT, *P WIN SORT; 



); 



// In: comparison callback 

// In: parameter to callback 

// Out: did sort cause change in order 



The client must create a function of the profile P_WIN_SORT_PROC that takes two windows (A,B) and 
returns -1 if A < B, if A == B, and +1 if A > B. The comparison will normally be based on information 
retrieved from the windows (for instance, msgLabelGetString). 



Arguments 



Com merits 



msgWinGetEnv 



Gets the current window environment. 
Takes P_WIN_ENV, returns STATUS. 

♦define msgWinGetEnv 



MakeMsg(clsWin, 47) 



// system font scale 

// system font 

// user font 

// device pixels per meter 



// environment being saved 



typedef struct WIN_ENV 
{ 

U8 scale; 

U16 sysFontld, 
userFontld; 

SIZE32 ppm; 
} WIN_ENV, *P_WIN_ENV; 
typedef struct WIN_SAVE_ENV 
{ 

WIN_ENV env; 

U32 sparel; 

U32 spare2; 
} WIN_SAVE_ENV, *P_WIN_SAVE_ENV; 

typedef struct WIN_RESTORE_ENV 

{ 
WIN_ENV env; // the saved environment 

BOOLEAN scaleChanged, 

sysFontldChanged, // these are true if the current 

userFontldChanged, // environment has changed from 

ppmWChanged, // the saved environment. 

ppmHChanged; 
U32 sparel; 
U32 spare2; 
} WIN_RESTORE_ENV, *P_WIN_RESTORE_ENV; 

The window environment is information filed with the root of each filed tree of windows. 

This message would not normally be used by application software. 



msgWinDumpTree 

In lieu of msgDump. Dumps a dense subset of information for the window and all it's children 
recursively. 

Takes pNull, returns STATUS. 

fdefine msgWinDumpTree MakeMsg(clsWin, 51) 

Comments Debug /DW 2 causes the input flags to be printed, otherwise the window flags are printed. 

This function may not work unless the debugging version ofwin.dll is being used. 
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ipsgWinHitDetect 

Locates the window "und 

Takes P_WIN_METRICS, returns STATUS. 



Locates the window "under" a point. ^ 

a 



O 

#define msgWinHitDetect MakeMsg(clsWin, 58) «8 

5 
o 

a 
Z 



Message 


typedef struct 




Arguments 


{ 






WIN 


parent , 
child; 




RECT32 


bounds ; 




WIN DEV 


device; 




WIN FLAGS 


flags; 




TAG 


tag; 




WIN OPTIONS 


options; 




} WIN_METRICS, 


* P_WIN_ 


Comments 


pAres->bounds. 


origin is a 



pArgs->bounds.origin is a point relative to the receiver. The window tree, starting with the root window, 
is searched for a window underneath this point. The result is returned in pArgs->child. 

If the search is NOT successful, pArgs->child will be objNull. 

^Messages from other classes 

msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments clsWin will save its instance data and file each direct child that has wsSendFile on. 

If pArgs->root is self, clsWin will file the window environment along with its instance data. The 
window environment is retrieved by self-sending msgWinGetEnv. If pArgs->pEnv is not pNull, the 
current environment info (WIN_SAVE_ENV) will be copied to the storage provided (pArgs->pEnv should 
either be pNull or a P_WIN_SAVE_ENV). Subclasses of clsWin can make use of pArgs->pEnv to look at 
the environment under which the window is being saved. The filed window environment will be used 
during msgRestore to adjust the window bounds and/or dirty the window layout if the restore 
environment is not the same as the saved environment. 

If wsFileNoBounds is on in selfs window style flags, the current bounds will not be filed. This will save 
space in the filed window. 

If selfs desired size has been computed (via msgWinGetDesiredSize during msgWinLayout 
processing), the desired size will be filed. 

For each child of self that has wsSendFile on, clsWin will do the following: 

If wsFilelnline is on in the child's window style flags, the class of the 
child window will be filed, and then the child will be sent msgSave with 
the following 0BJJ3AVE parameters: 

all fields as in *pArgs, 

objSave = pointer to current save environment 

This will file the child "inline" without the usual resource file object 
header. This will save storage, but the child will not have its own 
resld and can only be restored by restoring its parent. 
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If wsFilelnline is not on in the child's window style flags, the child 
window will be filed by sending msgResPut Object to pArgs->file with the 
child' s uid as pArgs . 

Returns 

stsWinNoEnv if pArgs->root != self and pArgs->pEnv is pNull 
See Abo msgRestore 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsWin will restore its instance data from pArgs->file. Each filed child window will also be restored. The 

window will be created on the window device returned from OSThisWinDev(). 

If the window environment was filed when the window was saved, the window environment will be 
restored and copied to pArgs->pEnv if it is not pNull (pArgs->pEnv must be either pNull or 
P_WIN_RESTORE_ENV). The current window environment will be retrieved using msgWinGetEnv and 
compared to the filed window environment. 

If wsFileNoBounds is on in selfs window style flags, the bounds will be set to (0, 0, 0, 0) and the 
window will be marked as layout-dirty (wsLayoutDirty will be or-ed into the window's style flags). 
Otherwise, the filed bounds will be restored and adjusted to compensate for differences in the 
save/restore-time device resolution and orientation. 

clsWin will or-in wsLayoutDirty into the window's style flags if any of the following are true (in this 
context "changed" means that the current window environment values do not match the window 
environment filed with the window tree): 

wsFileLayoutDirty is on in the window's style flagssystem font or system font scale has changeduser font 
has changedpixels-per-meter in x or y have changed 

Each child that was filed will be restored as follows: 

If wsFilelnline was on in the child's window style flags, the child's 
class will be read in from pArgs->file and msgRestore Instance will be 
sent to the classs with the following 0BJ_REST0RE parameters: 

all fields as in *pArgs 
object = msgNewDefaults to clsObject 

object. key = pArgs->ob ject. key; 
object. cap = pArgs->ob ject . cap; 
object. heap = pArgs->ob ject. heap; 

If wsFilelnline was not on in the child's window style flags, the child's 
resld will be read in from pArgs->file and the child will be restored 
by sending msgResReadObject to pArgs->file with the following 
RES_READ_0BJECT parameters: 

mode = resReadObjectOnce; 

objectNew = same as object in wsFilelnline case above 

After all of the children have been restored, they will be inserted into the restored parent. Note that the 
wsCaptureGeometry and wsSendGeometry protocol is not used for these inserts (e.g. the parent will 
not be sent msgWinlnsertOK, even if the parent has wsCaptureGeometry on). 

See Also msgSave 
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ages Sent to a Window Device 

As a rule applications should not send these messages to theScreen. They would be used if the 
application creates image devices. 

msgNew 

Creates a windowing device. 

Takes P_WIN_DEV_NEW, returns STATUS. Category: class message. 

Arguments typedef struct 
{ 

U16 initialWindows; // default window slots to allocate 
} WIN_DEV_NEW_ONLY, * P_WIN_DEV_NEW_ONLY ; 

typedef struct 
{ 

OBJECT_NEW object; 

WIN_DEV_NEW_ONLY winDev; 
} WIN_DEV_NEW, * P_WIN_DEV_NEW, 

IMG DEV NEW, * P IMG DEV NEW; 



msgNewDefaults 

Initializes the WIN_DEV_NEW structure to default values. 

Takes P_WIN_DEV_NEW, returns STATUS. Category: class message. 

fessesge typedef struct 

Arguments { 

OBJECT_NEW object; 

WIN_DEV_NEW_ONLY winDev; 
} WIN_DEV_NEW, * P_WIN_DEV_NEW, 
win. Dev. initialWindows = 100; 



msgWinDevGetRootWindow 

Passes back root window for receiver. 
Takes P_OBJECT, returns STATUS. 
tdefine msgWinDevGetRootWindow 



MakeMsg(clsWinDev, 10) 



msgWinDevBindScreen 

Binds window device to a screen. 
Takes P_CHAR, returns STATUS. 
tdefine msgWinDevBindScreen 



MakeMsg(clsWinDev, 6) 



msgWinDevBindPrinter 

Binds window device to an object of clsPrn. 
Takes OBJECT, returns STATUS. 
tdefine msgWinDevBindPrinter 



MakeMsg (clsWinDev, 7 ) 
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msgWinDevBindPixelmap 

Binds window device to a pixelmap. 

Takes P_WIN_DEV_PIXELMAP, returns STATUS. 

♦define msgWinDevBindPixelmap MakeMsg(clsWinDev, 11) 

Comments Note that you should not file the memory allocated by msgWinDevBindPixelmap, since the memory is 

device-dependant and you may be restored on a different screen device or system processor. 



Arguments 



msgWinDevSizePixelmap 

Computes the amount of memory needed for a single plane. 

Takes P_WIN_DEV_PIXELMAP, returns STATUS. 

♦define msgWinDevSizePixelmap MakeMsg(clsWinDev, 12) 



typedef struct 
{ 

OBJECT 

SIZE32 

U16 

SIZEOF 



device; 
size; 

planeCount ; 
planeSize; 



PP UNKNOWN pPlanes; 



// in = device to be "compatible" with 

// in = w, h of device to allocate 

//in = # planes to allocate 

// out = amount of memory for one plane 

//in = plane memory 



} WIN DEV PIXELMAP, * P WIN DEV PIXELMAP; 



Arguments 



msgWinDevSetOrientation 

Changes orientation of a window device. 
Takes PIX_DEV_ORIENT, returns STATUS. 
#define msgWinDevSetOrientation 

Enuml6 (PIX_DEV_ORIENT) 

{ 

pdUL = 0, 

pdUR = 1, 

pdLR = 2, 

pdLL = 3, 

pdOrientLandscapeNormal = pdLL, 

pdOrientPortraitNormal = pdUL, 

pdOr ient Lands capeReverse = pdUR, 

pdOrientPortraitReverse = pdLR 

}; 



MakeMsg(clsWinDev, 8) 



// not supported on printers 
// not supported on printers 



Argyttients 



msgPixDevGetMetrics 

Gets metrics of a pixelmap device. 

Takes P_PIX_DEV_METPJCS, returns nothing. 

♦define msgPixDevGetMetrics 



typedef struct 




i 
SIZE32 


size, 




ppm; 


U16 


planes; 


U16 


planeMask; 


U16 


planeNormalCount ; 


U16 


planeNormalMask; 


U16 


planePenCount ; 


U16 


planePenMask; 



MakeMsg(clsPixDev, 1) 



// size of device in DU4 

// pixel per meter in DU4 

// # of planes total 

// mask representing all planes 

// # of normal (not pen) planes 

// mask for the normal planes 

// # of pen planes 

// mask for the pen planes 
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PIX_DEV_ORIENT orient; // pdUL, pdLR, etc. 

P_UNKNOWN devPhysical, // handles to physical and 

devLogical; //logical device drivers 55 

U16 mode; // private flags, see pix. . . I 

OBJECT prn; // printer (or objNull) £ 

PP_UNKNOWN ppDryRunRgn; O 

} PIX DEV METRICS, * P PIX DEV METRICS; * 

o 
msgWinDevPrintPage z 

Repaints and outputs a page. 

Takes nothing, returns STATUS. 

tdefine msgWinDevPrintPage MakeMsg(clsWinDev, 9) 



^Messages sent to a drawing context 



« 



msgDrwCtxSetWindow 

Binds a drawing context to a window, returns old window. 

Takes WIN, returns WIN. 

♦define msgDrwCtxSetWindow MakeMsg(clsDrwCtx, 3) 



msgDrwCtxGetWindow 

Returns the window to which a drawing context is bound. 
Takes nothing, returns WIN. 

♦define msgDrwCtxGetWindow MakeMsg(clsDrwCtx, 4) 

tendif // WIN INCLUDED 
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This file contains the API for clsBorder. 

clsBorder inherits from clsEmbeddedWin. 

clsBorder supports drawing borders, backgrounds and shadows. Support is also provided for resize, drag 
and top window management. 

tifndef BORDER_INCLUDED 
♦define BORDER INCLUDED 



tinclude <win.h> 
# include <ewnew.h> 
tinclude <input.h> 



tifndef WIN_INCLUDED 

tendif 

tifndef EWNEW_INCLUDED 

tendif 

tifndef INPUT_INCLUDED 

tendif 



Common #def ines and typedefs 



tdefine hlpBorderResizeBottom 
tdefine hlpBorderResizeCorner 
tdefine hlpBorderResizeRight 
typedef OBJECT BORDER; 



Edge Styles 



tdefine bsEdgeNone 
tdefine bsEdgeLeft 
tdefine bsEdgeRight 
tdefine bsEdgeTop 
tdefine bsEdgeBottom 

// Borders on all edges 
tdefine bsEdgeAll 



Join Styles 



tdefine bsJoinSquare 
tdefine bsJoinRound 
tdefine bsJoinEllipse 
// 



Line Styles 



tdefine bsLineSingle 
tdefine bsLineDouble 
tdefine bsLineMarquee 
tdefine bsLineDashed 
tdefine bsLineDoubleMarquee 
tdefine bsLineDoubleDashed 
// 
// 
// 



MakeTag (clsBorder, 1 ) 
MakeTag (clsBorder, 2) 
MakeTag (clsBorder, 3) 



//no borders 

flagO // border on the left 

flagl // border on the right 

flag2 // border on the top 

flag3 // border on the bottom 

(bsEdgeLeft | bsEdgeRight | \ 
bsEdgeTop | bsEdgeBottom) 



// right -angle rectangle 

1 // round corner rectangle 

2 // ellipse instead of rectangle 

3 // unused (reserved) 



// solid ink 

1 // ink-white-ink lines 

2 // flowing dashed lines 

3 // dashed lines 

4 // double flowing dashed lines 

5 // double dashed lines 

6 // unused (reserved) 
. . // unused (reserved) 
15 // unused (reserved) 



328 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 

P^ Edge and Background Colors 



//no ink 
// black 
// 75% gray 
// 66% gray 
// 50% gray 
// 33% gray 
// 25% gray 
// white 

// use appropriate dc value 
// use custom RGB value 
// use the background ink 
// unused (reserved) 
// unused (reserved) 
// unused (reserved) 

bsInkExclusive can be or'ed into any ink to indicate that the specified ink should only be used if the 

window exclusively paints its pixels. If the window is transparent or shares clipping with its parent, 

bsInkTransparent will be used (i.e. nothing will be painted). 

tdefine bsInkExclusive flag4 

Borderlnk extracts the base ink from a border ink 



♦define bsInkTransparent 





#define bsInkBlack 


1 


tdefine bsInkGray75 


2 


#define bsInkGray66 


3 


#define bsInkGray50 


4 


tdefine bsInkGray33 


5 


tdefine bsInkGray25 


6 


tdefine bsInkWhite 


7 


tdefine bsInkAsIs 


8 


tdefine bsInkRGB 


9 


tdefine bsInkBackground 


10 


// 


11 


// 




// 


31 



tdefine Borderlnk (ink) 



((ink) & OxF) 



Ifr Shadow Styles: drawn on the bottom and right 



tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

II 

II 

II 



bsShadowNone 

bsShadowThinGray 

bsShadowThickGray 

bsShadowThinBlack 

bsShadowThickBlack 

bsShadowThinWhite 

bsShadowThickWhite 

bsShadowCustom 



15 



//no shadow 
// one line gray 
// two line gray 
// one line black 
// two line black 
// one line white 
// two line white 

// use shadowThickness and shadowlnk 
// unused (reserved) 
// unused (reserved) 
// unused (reserved) 



f^pr Units 



tdefine bsUnitsLayout 
tdefine bsUnitsDevice 
tdefine bsUnitsTwips 
tdefine bsUnitsPoints 

tdefine bsUnitsRules 
tdefine bsUnitsLines 

tdefine bsUnitsMetric 
tdefine bsUnitsMil 
tdefine bsUnitsFit Window 

tdefine bsUnitsFitWindowProper 



// 
// 
// 



// values are in layout units 

1 // values are in device units 

2 // values are in twips 
BorderUnitsCustom (bsUnits20x, bsUnitsTwips) 

// values are in points = 20 x twips 

3 // values are in rules 
BorderUnitsCustom (bsUnits20x, bsUnitsRules) 

// values are in lines = 20 x rules 

4 // values are in .01 mm 

5 // values are in .001 inch 

6 // values not specified — 
// compute to fit window 

7 // values not specified — 

// compute to fit window w/proper 
// aspect ratio 

8 // unused (reserved) 
. . // unused (reserved) 
15 // unused (reserved) 
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f^ Units Multiplier 

These values can be used with BorderUnitsCustom() to produce new units e.g. 
BorderUnitsCustom(bsUnits20x, bsUnitsTwips) indicates units are 20 x twips 



♦define bsUnitslx 
♦define bsUnits20x 
♦define bsUnitslOOx 
♦define bsUnitslOOOx 



♦define BorderUnitsCustom(mult, units) 
macros to extract base units and multiplier values 



// lx 

// 20x 

// lOOx 

// lOOOx 

((mult « 4) 



(units) ) 



♦define BorderUnits (units) 
♦define BorderUnitsMult (units) 



Pf^ Common Margin Values 



♦define bsMarginNone 
♦define bsMarginSmall 
♦define bsMarginMedium 
♦define bsMarginLarge 



((units) & OxOF) 
((units) » 4) 



//no inner margin 

1 // 1 unit 

2 // 2 units 
8 // 8 units 



PJr Resize Handles 



♦define bsResizeNone 
♦define bsResizeCorner 
♦define bsResizeBottom 
♦define bsResizeRight 
♦define bsResizeAll 



// no resize handles 
flagO // lower-right corner 
flagl // center-bottom 
flag2 // center-right 
(bsResizeCorner | bsResizeBottom | \ 
bsResizeRight) 



Drag Styles 



♦define bsDragNone 
♦define bsDragHoldDown 
♦define bsDragDown 
♦define bsDragMoveDown 



//no drag 

1 // drag on penHoldDown 

2 // drag on penDown 

3 // drag on penMoveDown beyond range 



Top Styles 



♦define bsTopNone 
♦define bsTopUp 
♦define bsTopDrag 
// 



// never top the window 

1 // top on penUp 

2 // top after drag 

3 // unused (reserved) 



Shadow Gap Styles 



♦define bsGapNone 
♦define bsGapWhite 
♦define bsGapTransparent 
// 



//no shadow gap 

1 // cleared to white 

2 // unpainted 

3 // unused (reserved) 



P^ Look Styles 



♦define bsLookActive 
♦define bsLooklnactive 
// 
// 



// usually black foreground color 

1 // usually gray66 foreground color 

2 // unused (reserved) 

3 // unused (reserved) 
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Alter Styles for preview and selected 



tdefine bsAlterNone 

#define bsAlterBackground 

♦define bsAlterBorders 

II 

typedef struct BORDER STYLE 



// don't alter anything 
// alter the background ink 
// alter the border ink 
// unused (reserved) 



U16 edge 

top 

drag 

resize 

maskBorders 

getDeltaWin 

spare 1 
U16 leftMargin 

rightMargin 
U16 bottomMargin 

topMargin 
U16 border Ink 

backgroundlnk 

previewAlter 

select edAlter 
U16 marginlnk 

marginUnits 

preview 

selected 

look 
U16 shadow 

shadowGap 

shadowThickness 

spare4 
U16 shadowlnk 

lineStyle 

spare5 
U16 lineUnits 

lineThickness 

join 
U16 propagateVisuals 

notifyVisuals 

spare3 



4, 
2, 
2, 

5, 
1, 
1, 
1; 
8, 
8; 
8, 



6, 
2, 
2; 
6, 
6, 
1, 
1, 
2; 
4, 
2, 
8, 
2; 
6, 
4, 
6; 



2; 

1, 
1, 
14; 



// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
//' 
// 
// 
// 
// 
// 
// 
// 
// 



edges to border 

top style (e.g. bsTopUp) 

drag style (e.g bsDragDown) 

resize handles (e.g. bsResizeCorner|bsResizeBottom) 

mask out edge, shadow, resize 

use msgBorderProvideDeltaWin 

unused (reserved) 

margin in marginUnits 



edge line color 

background fill color 

what to alter when previewing 

what to alter when selected 

ink for margin area (not implemented) 

units for left, right, bottom, top margins 

true/false 

true/false 

active/inactive 

type of shadow 

type of shadow gap 

custom shadow thickness, in lineUnits 

unused (reserved) 

custom shadow ink 

edge line style (e.g. bsLineSingle) 

unused (reserved) 

units for lineThickness and shadowThickness 

line thickness, in lineUnits 

how edges join together 

propagate changes in visuals to children 

send msgBorderSetVisuals to observers 

unused (reserved) 



} BORDER STYLE, *P BORDER STYLE; 



Default BORDER.STYLE: 

edge 
join 

lineStyle 
marginUnits 
resize 
move 
top 

leftMargin 
rightMargin 
bottomMargin 
topMargin 
look 

preview = 
selected 

propagateVisuals= 
notifyVisuals 
getDeltaWin 
maskBorders 
borderlnk = 
backgroundlnk 
marginlnk 



bsEdgeNone 

bsJoinSquare 

bsLineSingle 

bsUnitsLayout 

bsResizeNone 

bsDragNone 

bsTopNone 

bsMarginNone 

bsMarginNone 

bsMarginNone 

bsMarginNone 

bsLookActive 

false 

false 

false 

false 

false 

false 

bsInkBlack 

bsInkWhite 

bs InkBackground 
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shadow = bsShadowNone 

shadowGap = bsGapWhite 

shadowlnk = bsInkBlack 

shadowThickness = 1 

lineUnits = bsUnitsLines 

lineThickness = 1 

previewAlter = bsAlterNone 

selectedAlter = bsAlterNone 

Input event flags returned in INPUT_EVENT.flags indicates event was used to move/resize 

#define evBorderTaken evFlagO 

Tags used by resize or drag tracks. These will be the tags in TRACK_METRICS of * 

msgTrackProvideMetrics and msgTrackDone. O 

♦define tagBorderResize MakeTag(clsBorder, 4) ^ 

#define tagBorderDrag MakeTag(clsBorder, 5) *■ 

msgNew 

Creates a border window. 

Takes P_BORDER_NEW, returns STATUS. Category: class message. 

Arguments typedef struct BORDER_NEW_ONLY { 

BORDER_STYLE style; // overall style 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} BORDER_NEW_ONLY, BORDER_METRICS, 

*P_BORDER_NEW_ONLY , *P_BORDER_METRICS ; 

♦define borderNewFields \ 

embeddedWinNewFields \ 
BORDER_NEW_ONLY border; 

typedef struct { 

borderNewFields 
} BORDER_NEW, *P_BORDER_NEW; 

Comments If pArgs->border.style.maskBorders is true, style.resize is treated as though it is bsResizeNone, style.edge 

is treated as though it is bsEdgeNone, and style.shadow is treated as though it is bsShadowNone. 

If pArgs->style. resize is not bsResizeNone, pArgs->win.flags.input is altered to enable events needed for 
resizing. 

If pArgs->style.drag is not bsDragNone, pArgs->win.flags.input is altered to enable events needed for 
draging. 

If pArgs->style.top is not bsTopNone, pArgs->win.flags.input is altered to enable events needed for 
topping. 

msgNewDefaults 

Initializes the BORDERJMEW structure to default values. 

Takes P_BORDER_NEW, returns STATUS. Category: class message. 

Messoge typedef struct { 

Argymenfs borderNewFields 

} BORDER_NEW, *P_BORDER_NEW; 

Comments Zeroes out pNew->border and sets... 

pArgs->win. flags. style |= wsSendFile; 
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pArgs->border . style . shadowlnk 


= bsInkBlack; 


pArgs->border . style .border Ink 


= bsInkBlack; 


pArgs->border . style . marginlnk 


= bsInkBackground; 


pArgs->border . style .backgrounding 


= bsInkWhite; 


pArgs->border . style . lineUnits 


= bsUnitsLines; 


pArgs->border . style . lineThickness 


= 1; 


pArgs->border . style . shadowThickness 


= 1; 


pArgs->border . style . shadowGap 


= bsGapWhite; 


pArgs->border. style. previewAlter 


= bsAlterNone; 


pArgs->border . style . select edAlter 


= bsAlterNone; 



Arguments 



msgBorderGetStyle 

Passes back the current style values. 

Takes P_BORDER_STYLE, returns STATUS. 

#define msgBorderGetStyle MakeMsg(clsBorder, 1) 



typedef 


Struct BORDER_STYLE 


{ 


U16 


edge 


4, 


// 




top 


2, 


// 




drag 


2, 


// 




resize 


5, 


// 




maskBorders 


1, 


// 




getDeltaWin 


1, 


// 




sparel 


1, 


// 


U16 


leftMargin 


8, 


// 




rightMargin 


8, 


// 


U16 


bottomMargin 


8, 


// 




topMargin 


8, 


// 


U16 


borderlnk 


6, 


// 




backgroundlnk 


6, 


// 




previewAlter 


2, 


// 




selectedAlter 


2, 


// 


U16 


marginlnk 


6, 


// 




marginUnits 


6, 


// 




preview 


1, 


// 




selected 


1, 


// 




look 


2, 


// 


U16 


shadow 


4, 


// 




shadowGap 


2, 


// 




shadowThickness 


8, 


// 




spare4 


2, 


// 


U16 


shadowlnk 


6, 


// 




lineStyle 


4, 


// 




spare5 


6, 


// 


U16 


lineUnits 


6, 


// 




lineThickness 


8, 


// 




join 


2, 


// 


U16 


propagat eVi sual s 


1, 


// 




notifyVisuals 


1, 


// 




spare3 


V 


l; // 


} BORDER STYLE, *P BORDEI 


*_S1 


DYLE; 



edges to border 

top style (e.g. bsTopUp) 

drag style (e.g bsDragDown) 

resize handles (e.g. bsResizeCorner|bsResizeBottom) 

mask out edge, shadow, resize 

use msgBorderProvideDeltaWin 

unused (reserved) 

margin in marginUnits 



edge line color 

background fill color 

what to alter when previewing 

what to alter when selected 

ink for margin area (not implemented) 

units for left, right, bottom, top margins 

true/false 

true/false 

act i ve / inact i ve 

type of shadow 

type of shadow gap 

custom shadow thickness, in lineUnits 

unused (reserved) 

custom shadow ink 

edge line style (e.g. bsLineSingle) 

unused (reserved) 

units for lineThickness and shadowThickness 

line thickness, in lineUnits 

how edges join together 

propagate changes in visuals to children 

send msgBorderSetVisuals to observers 

unused (reserved) 



msgBorderSetStyle 



Sets all of the style values. 

Takes P_BORDER_STYLE, returns STATUS. 

tdefine msgBorderSetStyle MakeMsg(clsBorder, 2) 
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edges to border 

top style (e.g. bsTopUp) 

drag style (e.g bsDragDown) 

resize handles (e.g. bsResizeCorner|bsResizeBottom) 

mask out edge, shadow, resize 

use msgBorderProvideDeltaWin 

unused (reserved) 

margin in marginUnits 



edge line color 

background fill color 

what to alter when previewing 

what to alter when selected 

ink for margin area (not implemented) 

units for left, right, bottom, top margins 

true/false 

true/false 

active /inactive 

type of shadow 

type of shadow gap 

custom shadow thickness, in lineUnits 

unused (reserved) 

custom shadow ink 

edge line style (e.g. bsLineSingle) 

unused (reserved) 

units for lineThickness and shadowThickness 

line thickness, in lineUnits 

how edges join together 

propagate changes in visuals to children 

send msgBorderSetVisuals to observers 

unused (reserved) 



self-sends msgWinDirtyRect with pArgs specifying the rectangle around each border. 

Self-sends msgWinSetLayoutDirty(true), if new style results in new layout. 

If style.propagateVisuals is true, and propagateVisuals or any of the visual styles (look, backgroundlnk, 
previewAlter, selectedAlter, preview, or selected) change, msgBorderSetVisuals(pArgs) is sent to each 
child of self. 

If style.notifyVisuals is true and notifyVisuals or any of the visual styles change, msgNotifyObservers is 
self-sent with the following OBJ_NOTIFY_OBSERVERS parameters: 

msg = msgBorderSetVisuals; 

pArgs = pointer to new style struct; 

lenSend = SizeOf(BORDER_STYLE); 



Message 


typedef 


struct BORDER_STYLE { 




Arguments 


U16 


edge 


4, 


// 






top 


2, 


// 






drag 


2, 


// 






resize 


5, 


// 






maskBorders 


1, 


// 






getDeltaWin 


1, 


// 






sparel 


1; 


// 




U16 


leftMargin 


8, 


// 






rightMargin 


8; 


// 




U16 


bottomMargin 


8, 


// 






topMargin 


8; 


// 




U16 


borderlnk 


6, 


// 






backgroundlnk 


6, 


// 






previewAlter 


2, 


// 






selectedAlter 


2; 


// 




U16 


margin Ink 


6, 


// 






marginUnits 


6, 


// 






preview 


If 


// 






selected 


1, 


// 






look 


2; 


// 




U16 


shadow 


4, 


// 






shadowGap 


2, 


// 






s hadowThi ckne s s 


8, 


// 






spare 4 


2; 


// 




U16 


shadowlnk 


6, 


// 






lineStyle 


4, 


// 






spare5 


6; 


// 




U16 


lineUnits 


6, 


// 






lineThickness 


8, 


// 






join 


2; 


// 




U16 


propagat eVi sual s 


1, 


// 






notifyVisuals 


1, 


// 






spare3 


14; 


// 




} BORDER_STYLE, *P_BORDEI 


l_STYLE 


i 


Comments 


Self-sends mseWinDirtyRe 


Ct(pNu 


11) ii 



msgBorderSetStyleNoDirty 

Sets all of the style values. 

Takes P_BORDER_STYLE, returns STATUS. 

♦define msgBorderSetStyleNoDirty MakeMsg(clsBorder, 26) 
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typedef struct BORDER STYLE { 



U16 edge 

top 

drag 

resize 

maskBorders 

getDeltaWin 

sparel 
U16 leftMargin 

rightMargin 
U16 bottomMargin 

topMargin 
U16 borderlnk 

backgroundlnk 

previewAlter 

select edAlter 
U16 marginlnk 

marginUnits 

preview 

selected 

look 
U16 shadow 

shadowGap 

shadowThickness 

spare4 
U16 shadowlnk 

lineStyle 

spare5 
U16 lineUnits 

lineThickness 

join 
U16 propagateVisuals 

notifyVisuals 

spare3 



4, 
2, 
2, 
5, 

1, 
1, 
1; 



6, 
6, 
2, 
2; 
6, 
6, 
1, 
1, 
2; 
4, 
2, 
8, 
2; 
6, 
4, 
6; 
6, 
8, 
2; 
1, 
1, 
14; 



// edges to border 

// top style (e.g. bsTopUp) 

// drag style (e.g bsDragDown) 

// resize handles (e.g. bsResizeCorner|bsResizeBottom) 

// mask out edge, shadow, resize 

// use msgBorderProvideDeltaWin 

// unused (reserved) 

// margin in marginUnits 

// 

// 

// 

// edge line color 

// background fill color 

// what to alter when previewing 

// what to alter when selected 

// ink for margin area (not implemented) 

// units for left, right, bottom, top margins 

// true/false 

// true/false 

// active/inactive 

// type of shadow 

// type of shadow gap 

// custom shadow thickness, in lineUnits 

// unused (reserved) 

// custom shadow ink 

// edge line style (e.g. bsLineSingle) 

// unused (reserved) 

// units for lineThickness and shadowThickness 

// line thickness, in lineUnits 

// how edges join together 

// propagate changes in visuals to children 

// send msgBorderSetVisuals to observers 

// unused (reserved) 



} BORDER_STYLE, *PJ30RDER_STYLE; 

This message is the same as msgBorderSetStyle, except msgWinDirtyRect or msgWinSetLayoutDirty 
will not be self-sent, even if they new style parameters require repaint or relayout. 



msgBorderGetLook 

Passes back value of style.look. 
Takes P_U16, returns STATUS. 
#define msgBorderGetLook 



MakeMsg(clsBorder, 13) 



msgBorderSetLook 

Sets style.look as in msgBorderSetStyle. 

Takes U16 (bsLook...), returns STATUS. 

#define msgBorderSetLook MakeMsg(clsBorder, 12) 



msgBorderSetPreview 

Sets style.preview as in msgBorderSetStyle. 

Takes BOOLEAN, returns STATUS. 

tdefine msgBorderSetPreview MakeMsg(clsBorder, 8) 
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msgBorderGetPreview 

Passes back value of style.preview. 

Takes P_BOOLEAN, returns STATUS. 

tdefine msgBorderGetPreview MakeMsg(clsBorder, 9) 



msgBorderSetSelected 

Sets style.selected as in msgBorderSetStyle. 



Takes BOOLEAN, returns STATUS. g 

o 

#define msgBorderSetSelected MakeMsg(clsBorder, 16) 

3 



msgBorderGetSelected 

Passes back value of style.selected. 

Takes P_BOOLEAN, returns STATUS. 

tdefine msgBorderGetSelected MakeMsg(clsBorder, 17) 



* 



msgBorderPropagateVisuals 

Propagates visuals to children. 
Takes nothing, returns STATUS. 

#define msgBorderPropagateVisuals MakeMsg(clsBorder, 15) 
Comments Sends msgBorderSetVisuals(&style), where style is selfs current style, to each child. 



msgBorderSetDirty 

Sends msgBorderSetDirty(pArgs) to each child. 

Takes BOOLEAN, returns STATUS. 

#define msgBorderSetDirty MsgNoError (MakeMsg(clsBorder, 37)) 

Comments clsBorder will pass this message along to each of its children. Child windows can alter their visuals to 

display a clean/dirty look. For example, clsControl will self-send msgControlSetDirty(pArgs) when 
receiving this message. 



msgBorderGetDirty 

Passes back true if any child responds to msgBorderGetDirty with true; otherwise passes back false. 

Takes P_BOOLEAN, returns STATUS. 

#define msgBorderGetDirty MsgNoError (MakeMsg (clsBorder, 38)) 

Comments clsBorder will pass this message along to each of its children. The first child that responds with true will 

result in an answer of true. If no children are dirty, or there are no children, false will be returned. 

This message can be used to check the overall dirty/ clean visual state of a tree of border windows. 
clsControl will respond by passing back the value of visual dirty bit, style.dirty. 
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msgBorderGetForegroundRGB 

Passes back foreground RGB to use given current visuals. 

Takes P_SYSDC_RGB, returns STATUS. 

tdefine msgBorderGetForegroundRGB MakeMsg(clsBorder, 27) 

Comments Subclasses should use this message to determine the correct foreground color to use. For example, 

clsLabel will self-send msgBorderGetForegroundRGB in its response to msgWinRepaint to make sure 
and get the correct foreground color. 



msgBorderGetBackgroundRGB 

Passes back background RGB to use given current visuals. 

Takes P_SYSDC_RGB, returns STATUS. 

#define msgBorderGetBackgroundRGB MakeMsg (clsBorder, 28) 



msgBorderlnkToRGB 

Maps ink value (bsInkGray66, etc.) to RGB. 
Takes P_SYSDC_RGB, returns STATUS. 

tdefine msgBorderlnkToRGB MakeMsg (clsBorder, 29) 

Comments For example, bsInkGray66 maps to sysDcRGBGray66. 

msgBorderRGBToInk 

Maps RGB value to ink (bsInkGray66, etc). 
Takes P_SYSDC_RGB, returns STATUS. 

tdefine msgBorderRGBToInk MakeMsg (clsBorder, 30) 

Comments For example, sysDCRGBGray66 maps to bsInkGray66. 

If pArgs has no matching ink value, bsInkTransparent is passed back. 

msgBorderConvertUnits 

catagory: class or instance message Converts values from one unit to another. 

Takes P_BORDER_UNITS, returns STATUS. 

tdefine msgBorderConvertUnits MakeMsg (clsBorder, 39) 

Arguments typedef struct BORDER_UNITS { 

// in: window on target device 
// in: units for initial size.w/h 
// in: units for final size.w/h 
// in/out: initial /converted value 
// unused (reserved) 
} BORDERJJNITS, *P_BORDER_UNITS; 

Comments This message can be sent to clsBorder or an instance of clsBorder. clsBorder will convert pArgs->size 

from pArgs->fromUnits to pArgs->toUnits. If bsUnitsDevice is specified, pArgs->win should be set to a 
window on the corresponding device. 



WIN 


win; 


U16 


fromUnits; 


U16 


toUnits; 


SIZE32 


size; 


U32 


spare; 
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Message 
Arguments 



Comments 



msgBorderSetVisuals 

Sets only the visual fields from pArgs. 

Takes P_BORDER_STYLE, returns STATUS. 

#define msgBorderSetVisuals MakeMsg(clsBorder, 22) 



typedef struct BORDER STYLE { 



U16 edge 

top 

drag 

resize 

maskBorders 

getDeltaWin 

sparel 
U16 leftMargin 

rightMargin 
U16 bottomMargin 

topMargin 
U16 borderlnk 

backgroundlnk ' 

previewAlter 

selectedAlter 
U16 marginlnk 

marginUnits 

preview 

selected 

look 
U16 shadow 

shadowGap 

shadowThi ckne s s 

spare4 
U16 shadowlnk 

lineStyle 

spare5 
U16 lineUnits 

lineThickness 

join 
U16 propagateVisuals 

notifyVisuals 

spare3 



4, 
2, 
2, 
5, 

1, 
1, 
1; 



6, 
6, 
2, 
2; 
6, 
6, 
1, 
1, 
2; 
4, 
2, 
8, 
2; 
6, 
4, 
6; 
6, 
8, 
2; 
1, 
1, 
14; 



// edges to border 

// top style (e.g. bsTopUp) 

// drag style (e.g bsDragDown) 

// resize handles (e.g. bsResizeCorner|bsResizeBottom) 

// mask out edge, shadow, resize 

// use msgBorderProvideDeltaWin 

// unused (reserved) 

// margin in marginUnits 

// 

// 

// 

// edge line color 

// background fill color 

// what to alter when previewing 

// what to alter when selected 

// ink for margin area (not implemented) 

// units for left, right, bottom, top margins 

// true/false 

// true/false 

// active /inactive 

// type of shadow 

// type of shadow gap 

// custom shadow thickness, in lineUnits 

// unused (reserved) 

// custom shadow ink 

// edge line style (e.g. bsLineSingle) 

// unused (reserved) 

// units for lineThickness and shadowThickness 

// line thickness, in lineUnits 

// how edges join together 

// propagate changes in visuals to children 

// send msgBorderSetVisuals to observers 

// unused (reserved) 



8 



} BORDER STYLE, *P BORDER STYLE; 



Sets style.look, style.preview, and style.selected from pArgs as in msgBorderSetStyie. 

If style.backgroundlnk is not currently bsInkTransparent, sets style. backgroundlnk from pArgs as in 
msgBorderSetStyie. 



msgBorderGetBorderRect 

Passes back the rect on the border. 

Takes P_RECT32, returns STATUS. 

#define msgBorderGetBorderRect MakeMsg(clsBorder, 3) 

Comments The first pixel of this rect is on the border. This is the rectangle on which the border edges will be 

drawn, which is outside the inner margin. pArgs is in device units. 
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msgBorderlnsetToBorderRect 

Assumes given rect is window bounds, insets to border rect as in msgBorderGetBorderRect. 

Takes P_RECT32, returns STATUS. 

tdefine msgBorderlnsetToBorderRect MakeMsg (clsBorder, 7) 

Comments You can send this message to determine where the border rect would be with the given bounds. 

clsBorder will self-send this message during msgWinRepaint to determine the rect on which the border 
edges should be drawn. 

pArgs should be in device units. 

___ ^_^^__^ ____^ 

Passes back the rect after the inner margin. 

Takes P_RECT32, returns STATUS. 

tdefine msgBorderGetlnnerRect MakeMsg (clsBorder, 4) 

Comments The first pixel of this rect is inside the shadow, border edges and margin area. This is the outer-most 

usable area. pArgs is in device units. Subclasses should use this message to determine the area available to 
draw in after clsBorder has drawn all the shadows and borders. 

msgBorderlnsetToInnerRect 

Assumes given rect is window bounds, insets to inner rect as in msgBorderGetlnnerRect. 

Takes P_RECT32, returns STATUS. 

#define msgBorderlnsetToInnerRect MakeMsg (clsBorder, 18) 

msgBorderGetMarginRect 

Passes back the rect after the border. 
Takes P_RECT32, returns STATUS. 

tdefine msgBorderGetMarginRect MakeMsg (clsBorder, 31) 

Comments The first pixel of this rect is the start of the margin area. pArgs is in device units. 

msgBorderlnsetToMarginRect 

Assumes given rect is window bounds, insets to margin rect as in msgBorderGetMarginRect. 

Takes P_RECT32, returns STATUS. 

tdefine msgBorderlnsetToMarginRect MakeMsg (clsBorder, 35) 

msgBorderGetOuterSize 

Passes back the sum of the border, margin and shadow sizes for width and height. 

Takes P_SIZE32, returns STATUS. 

tdefine msgBorderGetOuterSize MakeMsg (clsBorder, 5) 

Comments Values are in device units. Subclasses can use this message to determine the space needed for the border 

area. For example, clsLabel will use this number to compute its total shrink-wrap size. 
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msgBorderGetOuterSizes 

Passes back the breakdown of the outer size requirements. 

Takes P_RECT32, returns STATUS. 

#define msgBorderGetOuterSizes MakeMsg(clsBorder, 36) 

Comments OuterSizes are insets from outer edge to inner rect. Note that this is not a true rectangle, each field (x, y, 

w, h) is a distance from the outer edge. The sum x+w is equivalent to the OuterSize w, the sum y+h is 
equivalent to the OuterSize h. Values are in device units. 

msgBorderGetOuterOffsets 

Passes back the distance from the outer edge to the border rect in each dimension. 

Takes P_RECT32, returns STATUS. 

#define msgBorderGetOuterOffsets MakeMsg(clsBorder, 25) 

Comments OuterOffsets are insets from outer edge to inner rect. Note that this is not a true rectangle, each field (x, 

y, w, h) is a distance from the outer edge. 

Values are in device units. 

This message may be subclassed to return the visual outer offsets. For example, clsFrame will return the 
outer offsets to the frame border window. 



msgBorderXOR 

Sets the raster-op to XOR and paints the background. 

Takes U16, returns STATUS. 

♦define msgBorderXOR MakeMsg(clsBorder, 33) 

Comments The U16 passed in is used as backgroundlnk. Using pArgs of bsInkWhite yields a true XOR, 

bsInkGray66 gives a graying effect. 



Comments 



msgBorderPaint 

Paints the border, background, shadow, etc. using msgWinBeginPaint. 

Takes VOID, returns STATUS. 

♦define msgBorderPaint MakeMsg(clsBorder, 34) 

msgBorderXOR 



msgBorderProvideDeltaWin 

catagory: ancestor window responsibility Receiver must provide window to be dragged, resized or 
topped. 

Takes P_WIN, returns STATUS. 

♦define msgBorderProvideDeltaWin MakeMsg(clsBorder, 23) 

clsBorder will respond by self-sending msgWInSend with the following WIN_SEND parameters: 

ws. flags = wsSendDefault; 
ws.lenSend = SizeOf (WIN_SEND) ; 
ws.msg = msgBorderProvideDeltaWin; 
ws.datafO] = objNull; 
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*pArgs will be set to ws.data[0]. 

This message is used by clsBorder if style.getDeltaWin is true to determine which window to 
drag/resize/top. 

See Mm msgWinSend 

msgBorderProvideBackground 

catagory: subclass responsibility Receiver must provide rect and ink for drawing background. 

Takes P_BORDER_BACKGROUND, returns STATUS. 

Argy merits typedef Struct BORDER_BACKGROUND { 

RECT32 rect; // in/out: background rect to fill 

U16 ink; // in/out: ink to fill with (e.g. bsInkWhite) 

U16 borderlnk; // in/out: ink to draw border with (e.g. bsInkBlack) 

U32 spare; // unused (reserved) 

} BORDER_BACKGROUND, *P_BORDER_BACKGROUND ; 

tdefine msgBorderProvideBackground MakeMsg (clsBorder, 24) 

Comments Self-sent during msgWinRepaint if style.preview or style.selected is true. pArgs defaults to current 

border rect, background and border inks. 

A subclass can catch this message and change any of the parameters. For example, clsMenuButton will 
alter the background rect if the menu button has a top or bottom border on, to back away previewing 
feedback from the border edge. 

msgBorderPaintForeground 

catagory: subclass window responsibility Receiver must paint the foreground, if any. 

Takes VOID, returns STATUS. 

tdefine msgBorderPaintForeground MakeMsg (clsBorder, 32) 

Comments clsBorder never sends this message. A subclass may send this message to force an ancestor class (e.g. 

clsLabel) to paint the foreground. 

clsBorder responds by doing nothing and returning stsOK. 

See Also msgBorderPaint 

msgBorderFlash 

Flashes self's window by drawing a thick border and erasing it. 

Takes VOID, returns STATUS. 

tdefine msgBorderFlash MakeMsg (clsBorder, 40) 

Comments clsBorder will flash a border around selfs window. This is used by msgBorderTop to hilight a window 

that is already on top. 

See Also msgBorderTop 

^___^_^_- . . _ _____ 

Tops the border window with optional UI feedback and/or bottoming. 

Takes U32, returns STATUS. 

tdefine bsTopFlash ((U32)flag0) // msgBorderFlash if already on top 
tdefine bsTopBottom ((U32)flagl) // send to bottom if already on top 
tdefine msgBorderTop MakeMsg (clsBorder, 41) 
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Comments If self is not already on top of its siblings, clsBorder will bring self to top. 

If pArgs has bsTopFlash on and self is already on top, clsBorder will self-send msgBorderFlash to flash a 
border around self. 

If pArgs has bsTopBottom on and self is already on top, clsBorder will re-insert self at the "bottom". 
The bottom is defined as the first child of the mainWin of theDesktop. If theDesktop does not exist, or 
it has no mainWin, self is placed at the bottom of its sibling stack. If self is not a sibling of the mainWin 
of theDesktop, nothing is done. 

See Also msgBorderFlash 



F Messages from other classes 



msgWInSend 

Sends a message up a window ancestry chain. 

Takes WIN_SEND, returns STATUS. 

Comments If pArgs->msg is msgBorderProvideDeltaWin and style.getDeltaWin is true, clsBorder will set 

pArgs->data[0] to self and return stsOK. This will result in self being the window that is 
dragged/resized/topped. 

msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments clsBorder will respond to input events that trigger dragging, resizing, or topping. 

If pArgs->devCode is msgPenHoldTimeout and style.drag is bsDragHoldDown, or pArgs->devCode is 
msgPenDown and style.drag is bsDragDown, or pArgs->devCode is msgPenMoveDown and style.drag 
is bsDragMoveDown and the pen has moved beyond a small threshold since the last msgPenDown, the 
following is done: 

msgGWinAbort(pNuli) is self-sent to terminate any gesture in progress. 

If style.getDeltaWin is true, msgBorderProvideDeltaWin is self-sentmsgWinSend to determine the 
window to be dragged. Otherwise,is used as the window to be dragged. 

msgTrackProvideMetrics is sent to the window to be dragged with_METRICS parameters as follows: 

msgNewDefaults is sent to clsTrack to initialize a TRACKJMETRICS 
struct and then: 

style. startThickness = tsThicknessDouble; 

win = parent of window to be dragged; 

client = self; 

clientData = window to be dragged; 

initRect = bounds of window to be dragged; 

constrainRect.size = size of window to be dragged; 

keepRect = rect around grabbed point; 

tag = tagBorderDrag; 

An instance of clsTrack is created and started via msgTrackStart. 

If pArgs->devCode is msgPenUp and style.top is bsTopUp and gWin.style.gestureEnable is false, a 
window to be topped is determined as in the window to be dragged above, and 
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msgBorderTop(bsTopBottom) is sent to the window to bring it to top (or take it to bottom if already 
on top). 

If pArgs->devCode is one of msgPenlnProxUp, msgPenEnterUp, or msgPenMoveUp, and style, resize is 
not bsResizeNone, and pArgs->xy is in one of the resize handle areas, the following is done: 

msgGWinAbort(pNull) is self-sent to terminate any gesture in progress. 

A window to be resized is determined as in the window to be dragged above,an instance of clsGrabBox 
is created with this window as its client.grabBox is sent msgGrabBoxShow(true) to start the resize 
feedback. 

If a drag or resize is done, pArgs->flags will have evBorderTaken turned on to indicate that clsBorder 
"took" the event. 

msgTrackDone 

Sent by a tracker when it's done. 

Takes P_TRACK_METRICS, returns STATUS. Category: client notification. 

ments If pArgs->tag is not tagBorderDrag, nothing is done and the message is passed to ancestor. 

Otherwise, clsBorder assumes pArgs->clientData is a window to be dragged and sends msgWinDelta to 
this window to change its origin to one based on pArgs->rect.origin. 

If style.top is bsTopDrag, the window to be dragged is also topped (brought to front) by sending it 
msgBorderTop(O) . 

msgTimerNotify 

Notifies the client that the timer request has elapsed. 

Takes P_TIMER_NOTIFY, returns nothing. Category: advisory message. 

Comments If self s lineStyle is bsLineMarquee or bsLineDoubleMarquee, clsBorder will animate the marquee and 

set the timer again. 

msgSelSelect 

Sets self to be the selection. 
Takes nothing, returns STATUS. 
Comments clsBorder responds by self-sending msgBorderSetSelected(true). 

msgSelYield 

The Selection Manager requires the release of the selection. 
Takes BOOLEAN, returns STATUS. 
Comments clsBorder responds by self-sending msgBorderSetSelected(false). 

msgGWinGesture: 

Called to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 
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Messages from other classes 

ts If pArgs->msg is xgslTap and style.top is bsTopUp, a window to be topped is determined and topped as 

in response to the input event msgPenUp. 

If pArgs->msg is xgsQuestion and style.resize is not bsResizeNone and pArgs->hotPoint falls over one 
of the resize handle areas, quick help for the resize handle is shown. 

See Also msglnputEvent 

msgWinRepaint 

Tells a window to repaint itself. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

Comments clsBorder responds by painting the background, shadow, resize handles, and border edges. 

msgBorderlnsetToBorderRect will be self-sent with a default of the current window bounds to allow the 
subclass to alter the rect on which the border will be drawn. 

If style. preview or style.selected are true, msgBorderProvideBackground is self-sent with the following 
BORDER.BACKGROUND parameters: 

rect = rectangle on which the border will be drawn, in device units; 

ink = backgroundlnk to be used; 

The resulting rect and ink are used during painting. 

If any of the specified inks have bsInkExclusive or-ed in, and the border window does not exclusively 
paint the pixels in its window, bsInkTransparent will be used. The test for a window exclusively painting 
the pixels in its window is as follows: 

define self Style to be self s window style flags 
define parentStyle to be parent's window style flags 

if (selfStyle & wsTransparent) 
return false; 

if (selfStyle & (wsClipSiblings | wsClipChildren) ) 
return true; 

if (! (selfStyle & wsParentClip) ) 
return true; 

if (parentStyle & wsTransparent) 
return true; 

if (parentStyle & wsClipChildren) 
return true; 

return false; 

If any of the specified inks are bsInkTransparent, nothing will be painted for that feature (e.g. 
backgroundlnk of bsInkTransparent results in no paint on the background). 

msgScrollWinProvideDelta 

Self-sent when scrolTWin.style.getDelta is set to true so that descendant or client can normalize the 
scroll if desired. 

Takes P_SCROLL_WIN_DELTA, returns STATUS. Category: descendant/client responsibility. 



344 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 

Comments clsBorder responds by computing a new origin based on pArgs->action and normalizing to prevent 

scrolling into part of a row or column. 

clsBorder will enumerate the leaf-level children and try to compute the row/column structure from the 
placement of the children. 

Normalization will occur in the direction of the scroll. For example, if the scroll action is moving 
upward (e.g sbLineUp), normalization will occur at the top of the view. 
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BUSY.H 



This file contains the API for clsBusy and theBusyManager. 

clsBusy inherits from clsObject. 

theBusyManager is typically the only instance of clsBusy. theBusyManager puts up and takes down a 
visual indication that the system is busy. 

Debugging Flags 

The clsBusy debugging flag is 'K'. Defined values are: 
flagO (0x0001) general busy on/off/inhibit 
flaglO (0x0400) never put up the busy UI 



#ifndef BUSY_INCLUDED 
#define BUSY_INCLUDED 

#include <clsmgr.h> 



tifndef CLSMGR_INCLUDED 
#endif 



msgBusyDisplay 

Requests a change in the state of the busy UI. 
Takes U32, returns STATUS. 

#define msgBusyDisplay MakeMsg (clsBusy, 9) 

#define busyOff // turn the busy UI off 

#define busyOn 1 // turn the busy UI on 

// these can be or-ed into busyOn or busyOff 

tdefine busyNoRef Count flagl // don't increment /decrement the ref count 

#define busyNoDelay flag2 // don't wait for timer to display 

You send this message to theBusyManager. 

theBusyManager maintains a reference count. Requests of busyOn increment the count, and requests of 
busyOff decrement the count. theBusyManager will put up the UI when the count goes from to 1, 
and take the UI down when the count goes from 1 to 0. 

If pArgs is busyOn I busyNoRefCount, and the reference count is already 1 or greater (i.e. the busy UI 
is already being displayed), nothing is done. 

If pArgs is busyOn I busyNoDelay, the busy UI will be displayed immediately, skipping the usual delay 
time. 

If pArgs is busyOff I busyNoRefCount, the reference count is set to and the busy UI is taken down. 

The busy UI will be displayed (i.e. hot spot at) the last xy specified via msgBusySetXY. If this is 
(minS32, minS32), the xy specified via msgBusySetDefaultXY will be used. 

When the busy UI is taken down, the xy for the next display of the busy UI is set to (minS32, minS32). 

msgBusylnhibit 
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msgBusylnhibit 

Inhibits/allows display of the busy UL 

Takes BOOLEAN, returns STATUS. 

tdefine msgBusylnhibit MakeMsg(clsBusy, 10) 

Comments You send this message to theBusyManager. 

theBusyManager maintains an inhibit reference count. Requests of TRUE increment the count, and 
requests of FALSE decrement the count. theBusyManager will take down the UI when the count goes 
from to 1, and allow subsequent displays of the busy UI (via msgBusyDisplay(busyOn)) when the 
count is zero. 

You can use msgBusylnhibit to prevent the busy UI from being displayed, even if requested by other 
parts of the system. 

See Abo msgBusyDisplay 



msgBusySetXY 

Specifies the position for the busy UI the next time it is shown. 

Takes P_XY32, returns STATUS. 

tdefine msgBusySetXY MakeMsg(clsBusy, 11) 

Comments You send this message to theBusyManager. The UI will be centered at pArgs the next time 

msgBusyDisplay(busyOn) is sent. 

pArgs should be in root window space. 

If the busy UI is currently being shown, this message is ignored. 

msgBusySetDefaultXY 

Specifies the default position for the busy UI the next time it is shown. 

Takes P_XY32, returns STATUS. 

♦define msgBusySetDefaultXY MakeMsg(clsBusy, 12) 

Comments The input system sends this message to theBusyManager when an input event has not been processed 

within the default time limit. The UI will be centered at pArgs the next time msgBusyDisplay(busyOn) 
is sent, if msgBusySetXY has not been used to specify a position. 

pArgs should be in root window space. 

msgBusyGetSize 

Passes back the size of the busy UI . 
Takes P_SIZE32, returns STATUS. 

tdefine msgBusyGetSize MakeMsg(clsBusy, 3) 

Comments theBusyManager will set *pArgs to the size of the default UL 
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BUTTON.H 



This file contains the API definition for clsButton. 

clsButton inherits from clsLabel. 

Buttons are labels, but with input behavior. Buttons also have a state value: on or off. Buttons notify 
their client when certain input events occur. clsButton make extensive use of its ancestors display 
capabilities, particularly clsBorder and clsLabel. 



tifndef BUTTON_INCLUDED 
tdefine BUTTON_INCLUDED 

#include <label.h> 



#ifndef LABEL_INCLUDED 
tendif 



Common #defines and ffypedefs 



typedef OBJECT 



BUTTON; 



Contact Styles 



Use one of these values in button's style.contact. 



tdefine bsContactMomentary 

tdefine bsContactToggle 1 

tdefine bsContactLockOn 2 

// 3 



// push-on, release-off 
// push-on, push-off 
// push-on, stays on 
// unused (reserved) 



Feedback Styles 



Use one of these values in button's style.feedback. 



tdefine bsFeedbacklnvert 





// invert on/off 


tdefine bsFeedbackDecorate 


1 


// use onDecorat ion/off Decoration 


tdefine bsFeedbackNone 


2 


//no feedback 


tdefine bsFeedback3D 


3 


// 3D shadow effect 


tdefine bsFeedbackBox 


4 


// boxed outline 


// 


5 


// unused (reserved) 


// 




// unused (reserved) 


// 


7 


// unused (reserved) 



pArgs Styles 

Use one of these values in buttons style.pArgs. 



tdefine bsPargsData 
tdefine bsPargsValue 
tdefine bsPargsUID 
// 



// pArgs is data 

1 // pArgs is current value 

2 // pArgs is button's UID 

3 // unused (reserved) 
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Manager Styles 



Use one of these values in button's style.manager. 



#define bsManagerNone 

♦define bsManagerParent 

tdefine bsManagerClient 

// 

typedef struct BUTTON STYLE 



U16 contact 

feedback 

notifyDetail 

notifyWithMsg 

on 

manager 

pArgs 

halfHeight 

spare 1 
U16 onDecoration 

offDecoration 

spare 



2, 
4, 
1, 
1, 
1, 
2, 
2, 
I, 
2; 
5, 
5, 
6; 



//no manager 

1 // parent is the manager 

2 // client is the manager 

3 // unused (reserved) 

// push behavior 

// invert, decorate, etc. 

// notify manager of BeginPreview etc. 

// send specified msg & data 

// button state: true == on 

// button manager style 

// which pArgs to send with msg 

// half-height borders 

// unused (reserved) 

// label decoration when on (see label. h) 

// label decoration when off (see label. h) 

// unused (reserved) 



} BUTTON STYLE, *P BUTTON STYLE; 



Default BUTTON STYLE: 



contact 

feedback 

onDecoration 

offDecoration 

notifyDetail 

notifyWithMsg 

pArgs 

on 

halfHeight 



= bsContactMomentary 

= bsFeedbacklnvert 

= lsDecorationNone 

= lsDecorationNone 

= false 

= true 

= bsPargsData 

= false 

= false 



typedef struct BUTTON_NOTIFY { 

OBJECT button; // uid of sender 
MESSAGE msg; 
U32 data; 
MESSAGE detail; 
U32 spare; 



// defined message or some other data 

// pArgs for message or some other data 

// msgButtonBeginPreview, etc. 

// unused (reserved) 



} BUTTON NOTIFY, *P BUTTON NOTIFY; 



P" Messages 



Arguments 



msgNew 

Creates a button window. 

Takes P_BUTTON_NEW, returns STATUS. Category: class message. 



typedef struct BUTTON_NEW_ONLY { 
BUTTON_STYLE style; 
MESSAGE msg; 
U32 data; 

U16 onCustomGlyph; 



U16 



offCustomGlyph; 



U32 spare; 

} BUTTON_NEW_ONLY, BUTTON_METRICS, 

*P_BUTTON_NEW_ONLY , *P_BUTTON_METRICS ; 

tdefine buttonNewFields \ 
labelNewFields \ 



// overall style 

// message to send or other data 

// pArgs for msg or other data 

// glyph to use for 

// lsDecorationCustomLeft/Right 

// glyph to use for 

// lsDecorationCustomLeft/Right 

// unused (reserved) 
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BUTTON_NEW_ONLY button; 

typedef struct BUTTON_NEW { 

buttonNewFields 
} BUTTONJJEW, *P_BUTTON_NEW; 

Comments The rest of this description uses the following abbreviations: 

on = pArgs->button. style. on; 

pButton = fcpArgs ->butt on. style; 

pBorder = &pArgs->border. style, 

pLabel = &pArgs->label. style, 

If pButton->feedback is bsFeedbacklnvert, sets 

O 

pBorder->preview = on; O 



If pButton-> feedback is bsFeedback3D, sets 

pBorder->join = bsJoinSquare; 

pBorder->previewAlter = bsAlterNone; 

pBorder->edge = bsEdgeTop | bsEdgeLeft; 

pBorder->shadowGap = bsGapNone; 

pBorder->preview = on; 
if (on) { 

pBorder->borderInk = bsInkBlack; 

pBorder->backgroundInk = bsInkGray66; 

pBorder->shadow = bsShadowThinWhite; 
} else { 

pBorder->borderInk = bsInkWhite; 

pBorder->backgroundInk = bsInkGray33; 

pBorder->shadow = bsShadowThinGray; 
} 

If pButton->feedback is bsFeedbackDecorate, sets 

pLabel->decoration = on ? 

pArgs->button . style . onDecoration : 
pArgs->button. style. off Decoration; 



msgNewDefaults 

Initializes the BUTTON_NEW structure to default values. 

Takes P_BUTTON_NEW, returns STATUS. Category: class message. 



Aessage typedef struct BUTTON_NEW { 

l.rgymepfs buttonNewFields 

} BUTTON_NEW, *P_BUTTON_NEW; 

:«im!¥ienfs Zeroes out pArgs->button and sets: 



pArgs->win. flags. input |= inputTip | inputEnter | inputExit; 
pArgs->win. flags. style |= wsFilelnline; 

pArgs->border. style. edge = bsEdgeAll; 
pArgs->border. style. join = bsJoinSquare; 
pArgs->border. style. shadow = bsShadowThinBlack; 
pArgs->border. style. border Ink = bsInkGray66; 

pArgs->control.style.previewEnable = true; 

pArgs->label. style. xAlignment = IsAlignCenter; 
pArgs->label.style.yAlignment = IsAlignCenter; 

pArgs->button. style. not if yWithMsg = true; 
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msgButtonGetMetrics 



Passes back the current metrics. 

Takes P_BUTTON_METRICS, returns STATUS. 

♦define msgButtonGetMetrics MakeMsg(clsButton, 1) 



Comments 



msgButtonSetMetrics 

Sets the metrics. 

Takes P_BUTTON_METRICS, returns STATUS. 

♦define msgButtonSetMetrics MakeMsg(clsButton, 2) 

If style.on changes, the button does the following: 



If style.contact != bsContactMomentary, self-sends msgControlSetDirty, true. 

Self-sends msgButtonNotifyManager with msg = msgButtonDone. 

Self-sends msgButtonNotify with detail of msgButtonAcceptPreview. This results in either 
msgButtonNotify or a client-specified message to the client. Alters border and label styles to reflect 
the new "on" value (see msgNew description). 

Changes to style.feedback and style.on/offDecoration result in appropriate changes to the Border and 
Label styles. 



JVk»soge 
Arguments 



msgButtonGetStyle 

Passes back the current style values. 

Takes P_BUTTON_STYLE, returns STATUS. 

♦define msgButtonGetStyle MakeMsg(clsButton, 3) 



typedef struct BUTTON_STYLE { 



U16 contact 


2, 


// 


feedback 


4, 


// 


notifyDetail 

notifyWithMsg 

on 


1, 
1, 
1, 


// 
// 
// 


manager 
pArgs 
half Height 
sparel 
U16 onDecoration 


2, 
2, 

1, 
2; 
5, 


// 
// 
// 
// 
// 


offDecoration 


5, 


// 


spare 
} BUTTON_STYLE, *P_BUTT01 


6; 

J STYLE 


// 

i 



push behavior 

invert, decorate, etc. 

notify manager of BeginPreview etc. 

send specified msg & data 

button state: true == on 

button manager style 

which pArgs to send with msg 

half -height borders 

unused (reserved) 

label decoration when on (see label. h) 

label decoration when off (see label. h) 

unused (reserved) 



msgButtonSetStyle 

Sets the style values. 

Takes P_BUTTON_STYLE, returns STATUS. 

♦define msgButtonSetStyle MakeMsg(clsButton, 4) 



Message 


typedef struct BUTTON ST1 


fLE 


Arguments 


U16 contact 


2, 




feedback 


4, 




notifyDetail 


1, 




notifyWithMsg 


1, 



// push behavior 

// invert, decorate, etc. 

// notify manager of BeginPreview etc. 

// send specified msg & data 
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on 

manager 
pArgs 

halfHeight 
spare 1 
U16 onDecoration 
offDecoration 
spare 



1, 
2, 
2, 
1, 
2; 
5, 
5, 
6; 



// button state: true == on 

// button manager style 

// which pArgs to send with msg 

// half -height borders 

// unused (reserved) 

label decoration when on (see label. h) 
label decoration when off (see label. h) 



// 
// 



// unused (reserved) 



Comments 



} BUTTON_STYLE, *P_BUTTON_STYLE; 

Reacts to changes in style.on and other style values as in msgButtonSetMetrics. 



msgButtonGetMsg 

Passes back metrics, msg. 

Takes P_MESSAGE, returns STATUS. 

♦define msgButtonGetMsg MakeMsg(clsButton, 5) 



msgButtonSetMsg 

Sets metrics, msg. 

Takes MESSAGE, returns STATUS. 

tdefine msgButtonSetMsg MakeMsg(clsButton, 6) 



msgButtonGetData 

Passes back metrics, data. 
Takes P_U32, returns STATUS. 
♦define msgButtonGetData 



MakeMsg(clsButton, 7) 



msgButtonSetData 

Sets metrics, data. 

Takes U32, returns STATUS. 

#define msgButtonSetData 



MakeMsg(clsButton, 8) 



msgButtonSetNoNotify 

Sets the value of the button (i.e. style.on) without notifying. 

Takes BOOLEAN, returns STATUS. 

#define msgButtonSetNoNotify MakeMsg(clsButton, 17) 

Comments pArgs must be true or false. The button s manager and client are not notified. Alters border and label 

styles to reflect new on value (see msgNew description). 



Comment's 



msgButtonButtonShowFeedback 

Shows the feedback for an on/off button if pArgs is true/false. 

Takes BOOLEAN, returns STATUS. Category: self-sent. 

♦define msgButtonShowFeedback MakeMsg(clsButton, 19) 

This message is self-sent by clsButton to change the on/off feedback shown to the user. For example, 
when a button with a contact style of bsContactToggle is pressed and msgControlBeginPreview is 
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received, clsButton self-sends msgButtonShowFeedback(!style.on) to show the user what will happen 
when the pen is lifted. 

Subclasses can handle the message and show the appropriate feedback for the new state. 

Messages Sent to Button # s Manager 

msgButtonDone 

Sent via msgWinSend to the manager when button receives msgControlAcceptPreview. 
Takes UID, returns STATUS. Category: manager notification. 

#define msgButtonDone MakeMsg (clsButton, 16) 

msgButtonBeginPreview 

Sent via msgWinSend to the manager when button receives msgControlBeginPreview. 
Takes UID, returns STATUS. Category: manager notification, 
tdefine msgButtonBeginPreview MakeMsg (clsButton, 9) 

Comments Only sent if style.notifyDetail is true. 

msgButtonUpdatePreview 

Sent via msgWinSend to the manager when button receives msgControlUpdatePreview. 
Takes UID, returns STATUS. Category: manager notification, 
tdefine msgButtonUpdatePreview MakeMsg (clsButton, 10) 

Comments Only sent if style.notifyDetail is true. 



msgButtonRepeatPreview 

Sent via msgWinSend to the manager when button receives msgControlRepeatPreview. 
Takes UID, returns STATUS. Category: manager notification, 
tdefine msgButtonRepeatPreview MakeMsg (clsButton, 11) 

Only sent if style.notifyDetail is true. 



msgButtonCancelPreview 

Sent via msgWinSend to the manager when button receives msgControlCancelPreview. 
Takes UID, returns STATUS. Category: manager notification. 
tdefine msgButtonCancelPreview MakeMsg (clsButton, 12) 

Comments Only sent if style.notifyDetail is true. 

msgButtonAcceptPreview 

Sent via msgWinSend to the manager when button receives msgControlAcceptPreview. 
Takes UID, returns STATUS. Category: manager notification. 
tdefine msgButtonAcceptPreview MakeMsg (clsButton, 13) 

Ceramet-its Only sent if style.notifyDetail is true. 
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Messages Defined by Other Classes 



msgButtonNotifyManager 

Sent to self when button wants to notify its manager. 

Takes P_BUTTON_NOTIFY, returns STATUS. Category: self-sent. 

#define msgButtonNotifyManager MakeMsg(clsButton, 18) 

Message typedef struct BUTTONJNOTIFY { 

Arguments OBJECT button; // uid of sender 

MESSAGE msg; // defined message or some other data 

U32 data; // pArgs for message or some other data 

MESSAGE detail; // msgButtonBeginP review, etc. 

U32 spare; // unused (reserved) O 

} BUTTON_NOTIFY, *P_BUTTON_NOTIFY; ° 

Comments A button responds to this by sending msgWinSend with the following WIN_SEND parameters to its 

manager: 

flags = wsSendDefault; 
lenSend = SizeOf (WIN_SEND) ; 
msg = pArgs->msg; 
data[0] = pArgs->data; 

msgButtonNotify 

Sent to self when button wants to notify its client. 

Takes P_BUTTON_NOTIFY, returns STATUS. Category: client notification. 

#define msgButtonNotify MakeMsg(clsButton, 14) 

Message typedef struct BUTTON_NOTIFY { 

Arguments OBJECT button; // uid of sender 

MESSAGE msg; // defined message or some other data 

U32 data; // pArgs for message or some other data 

MESSAGE detail; // msgButtonBeginPreview, etc. 

U32 spare; // unused (reserved) 

} BUTTON_NOTIFY, *P_BUTTON_NOTIFY; 

Comments If style. notifyWithMessage is true, pArgs->msg is sent to the button's client with the pArgs of 

pArgs->data or as specified by style.pArgs. 

Otherwise, msgButtonNotify is sent to the button's client with the following BUTTON.NOTIFY 
parameters: 

button = self; 

msg = pArgs->msg; 

data = pArgs->data; 

detail = pArgs->detail; 



Messages Defined by Other Classes 



msgBorderGetForegroundRGB 

Passes back foreground RGB to use given current visuals. 

Takes P_SYSDC_RGB, returns STATUS. 

Comments If style.feedback is bsFeedback3D and border.style.look is bsLooklnactive, passes back 

sysDcRGBGray66. Otherwise, calls ancestor. 
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msgControlBeginPreview 

Self-sent when msgPenDown is received. 

Takes P_EVENT, returns STATUS. Category: self-sent. 

Button computes new on value according to style.feedback (e.g. bsContactToggle results in on = 
Istyle.on). 

Alters border and label styles to reflect new on value and self-sends msgWinUpdate to repaint 
immediately, style, on is not changed. 

If style.contact is not bsContactMomentary, self sends msgControlSetDirty, true. 

If style.notifyDetail is true, self-sends msgButtonNotifyManager, which results in msgWinSend to the 
manager. Also, if control.style.previewRepeat is true, self-sends msgButtonNotify which results in client 



notification. 



msgControlUpdatePreview 

Self-sent when msgPenMoveDown is received. 
Takes P_EVENT, returns STATUS. Category: self-sent. 
Comments If style.notifyDetail is true, notifies manager and client as in msgControlBeginPreview. 

msgControlRepeatPreview 

Self-sent if style.repeatPreview is true. Initial delay is 600ms, then immediate repeat until msgPenUp. 
Takes P_EVENT, returns STATUS. Category: self-sent. 
Comments If style.notifyDetail is true, notifies manager and client as in msgControlBeginPreview. 

msgControlCancelPreview 

Self-sent when control.style.previewGrab is false and msgPenExitDown is received. 

Takes P_EVENT, returns STATUS. Category: self-sent. 

Comments Clients or subclasses can send this to a control to cancel existing preview. 

Alters border and label styles to reflect current style, on value and self-sends msgWinUpdate to repaint 
immediately. This undoes the visual effects of msgControlBeginPreview. 

If style.notifyDetail is true, notifies manager and client as in msgControlBeginPreview. 

msgControlAcceptPreview 

Self-sent when msgPenUp is received. 
Takes P_EVENT, returns STATUS. Category: self-sent. 
Comments If gestures are enabled this message is not sent until msgGWinGesture is received with xgslTap. 

Self-sends msgControlSetValue with on value computed as in msgControlBeginPreview. 

msgControlSetValue 

Sets style.on. 

Takes S32, returns STATUS. 
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Comments Updates visuals to reflect new on value as in msgButtonSetMetrics. 

Self-sends msgButtonNotifyManager with the following BUTTON_NOTIFY parameters (this results in 
msgWinSend to the manager): 

button = self; 

msg = msgButtonDone; 

data = self; 

Self-sends msgButtonNotify with the following BUTTON_NOTIFY parameters (this results in client 
notification): 

button = self; * 

msg - metrics. msg; § 

data = metrics. data; ^ 

detail = msgButtonAcceptPreview; ^ 



msgControlGetValue 

Passes back the style.on. 
Takes P_S32, returns STATUS. 
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CHMGR.H 



This file contains the API for clsChoiceMgr. 

clsChoiceMgr inherits from clsM anager. 

Choice managers serve as tkTable managers in tables of buttons. 

A choice manager, when plugged in as the manager of a tkTable of buttons, responds to the 
msgWinSend's generated by the buttons and makes the entire group perform as a choice. 



fy Debugging Flags 



The clsChoiceMgr debugging flag is 'K'. Defined values are: 

flagO (0x0001) general info 

tifndef CHMGR_INCLUDED 
♦define CHMGR_INCLUDED 

tinclude <manager.h> 



tifndef MANAGER_INCLUDED 
tendif 



p Common #defines and typedefs 



typedef OBJECT 



CHOICE MGR; 



msgNew 

Creates a choice manager. 

Takes P_CHOICE_MGR_NEW, returns STATUS. Category: class message. 

Arguments typedef struct CHOICE_MGR_NEW_ONLY { 

U32 spare; // unused (reserved) 

} CHOICE_MGR_NEW_ONLY, *P_CHOICE_MGR_NEW_ONLY; 

Idefine choiceMgrNewFields \ 
manage rNewFie Ids \ 

CHOICE_MGR_NEW_ONLY choiceMgr; 

typedef struct CHOICE_MGR_NEW { 

choiceMgrNewFields 
} CHOICE MGR NEW, *P CHOICE MGR NEW; 



Message 
Arguments 



Comments 



msgNewDefaults 

Initializes the CHOICE_MGR_NEW structure to default values. 

Takes P_CHOICE_MGR_NEW, returns STATUS. Category: class message. 

typedef struct CHOICE_MGR_NEW { 

choiceMgrNewFields 
} CHOICE_MGR_NEW, *P_CHOICE_MGRJJEW; 

clsChoiceManager has no instance data of its own. 
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msgChoiceMgrGetOnButton 

Gets the current on button. Passes back objNull if no button is on. 

Takes P_UID, returns STATUS. 

tdefine msgChoiceMgrGetOnButton MakeMsg (clsChoiceMgr, 1) 



msgChoiceMgrSetOnButton 

Sets the current on button. 

Takes UID, returns STATUS. 

tdefine msgChoiceMgrSetOnButton MakeMsg (clsChoiceMgr, 2) 

Comments Since the choiceMgr will use msgControlSetValue to turn the button on, that button's normal 

notification protocol will be invoked. 

All buttons are turned off if message argument is objNull. 



msgChoiceMgrSetNoNotify 

Like msgChoiceMgrSetOnButton, but no notifications are generated. 

Takes UID, returns STATUS. 

tdefine msgChoiceMgrSetNoNotify MakeMsg(clsChoiceMgr, 3) 



Messages from Other Classes 



sturn Veil 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes P_WIN_SEND, returns STATUS. 

Comments clsChoiceMgr responds when pArgs->msg is msgButtonBeginPreview, msgButtonCancelPreview, or 

msgButtonDone. If pArgs->msg is anything else, clsChoiceMgr just returns stsManagerContinue. 

For these three messages, clsChoiceMgr will make the set of entry windows act as a group. 

stsManagerContinue clsChoiceMgr always returns this so that the caller will continue to propagate the 
msgWinSend. 
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This file contains the API for clsChoice. 

clsChoice inherits from clsTkTable. 

Choices are tkTables of buttons that act as exclusive choices. 

Note that msgNewDefaults to clsChoice results in a prototypical new struct whose values describe a 
button of contact style bsContactLockOn. This is correct for choices that always have one button on, 
but this won't work if you want a choice that can have or 1 buttons on. In this case, making each 
button child have a contact style of bsContactToggle will achieve the desired effect. Here is the 
appropriate code. 

Ob jCallWarn (MsgNewDefaults, clsChoice, fcchoiceNew) ; 

choiceNew . tkTable .pButtonNew->button. style . contact = bsContactToggle; 

Ob jCallRet (msgNew, clsChoice, fcchoiceNew, s) ; 

See the documentation for msgTkTableChildDefaults below. 



#ifndef CHOICE_INCLUDED 
♦define CHOICE_INCLUDED 

tinclude <tktable.h> 



tifndef TKTABLE_INCLUDED 
tendif 



Common #defines and typedefs 

typedef OBJECT CHOICE; 

typedef struct CHOICE_STYLE { 

U16 spare; // unused (reserved) 
} CHOICE_STYLE, *P_CHOICE_STYLE; 

Informational return status returned by msgControlGetValue if choice has no value 

♦define stsChoiceNoValue MakeWarning (clsChoice, 1) 



msgNew 

Creates a choice (and its nested button windows). 

Takes P_CHOICE_NEW, returns STATUS. Category: class message. 

Arguments typedef struct CHOICE_NEW_ONLY { 

CHOICE_STYLE style; // overall style 
U32 value; // tag of on button 

U32 spare; // unused (reserved) 

} CHOICE_NEW_ONLY, *P_CHOICE_NEW_ONLY; 

tdefine choiceNewFields \ 
tkTableNewFields \ 
CHOICE_NEW_ONLY choice; 

typedef struct CHOICE_NEW { 

choiceNewFields 
} CHOICE NEW, *P CHOICE NEW; 
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Comments Will create a default instance of clsChoiceMgr if the incoming pArgs->tkTable. manager is null. The uid 

of the created manager will be an out parameter. 

After the manager has been set up, clsChoice will use msgControlGetValue to find the button that is 
'on', and then send msgChoiceMgrSetNoNotify to the manager to tell the manager which button is 



on 



Messoge 
Arguments 



Comments 



msgNewDefaults 

Initializes the CHOICE_NEW structure to default values. 

Takes P_CHOICE_NEW, returns STATUS. Category: class message. 

typedef struct CHOICE_NEW { 

choiceNewFields 
} CHOICE_NEW, *P_CHOICE_NEW; 

Sets up tkTable.pButtonNew to create buttons by default. Zeroes out pNew.choice and sets: 

pArgs->gWin. style. gestureEnable = false; 

pArgs->tableLayout. style. growChildHeight = false; 
pArgs->tableLayout .style. growChildWidth = true; 

pArgs->tableLayout . numCols . constraint = tlAbsolute; 
pArgs->tableLayout.numCols. value = 1; 

pArgs->tableLayout .numRows. constraint = tllnfinite; 

pArgs->tableLayout . colWidth . constraint = tlChildrenMax; 
pArgs->tableLayout.colWidth.gap = 0; 

pArgs->tableLayout .rowHeight . constraint = tlGroupMax; 
pArgs->tableLayout.rowHeight.gap - 0; 

pArgs->tkTable. manager = objNull; 



FM m KIM 

Instance Messages 



Message 
Arguments 



msgChoiceGetStyle 

Gets the style of the receiver. 

Takes P_CHOICE_STYLE, returns STATUS. 

tdefine msgChoiceGetStyle MakeMsg (clsChoice, 1) 

typedef struct CHOICE_STYLE { 

U16 spare; // unused (reserved) 
} CHOICE STYLE, *P CHOICE STYLE; 



nessesge 
krguments 



msgChoiceSetStyle 

Sets the style of the receiver. 

Takes P_CHOICE_STYLE, returns STATUS. 

tdefine msgChoiceSetStyle MakeMsg (clsChoice, 2) 

typedef struct CHOICE_STYLE { 

U16 spare; // unused (reserved) 
} CHOICE STYLE, *P CHOICE STYLE; 



CHOICE. H 361 

Messages from Other Classes 



msgChoiceSetNoNotify 

Like msgControlSetValue (see below), but without button notifications. 
Takes TAG, returns STATUS. 

tdefine msgChoiceSetNoNotify MakeMsg(clsChoice, 3) 
;ommenfs Using this message avoids button notifications being sent out to their clients. 



Messages from Other Classes 



msgFree 

Sent as the last of three msgs to destroy an object. 

Takes OBJ.KEY, returns STATUS. 

Comments If the choice had created its own TK_TABLE_NEW_ONLY. manager at msgNew time, the manager will be 

sent msgDestroy. 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

C0mments clsChoice responds by restoring its instance data. If the choice had created its own 

TK_TABLE_NEW_ONLY. manager at msgNew time, a new one is created from clsChoiceMgr. 

msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

c®mments clsChoice responds by filing away its instance data. It will remember whether clsChoice created its own 

TK_TABLE_NEW_ONLY.manager at msgNew time. 

msgWinSend 

Sends a message up a window ancestry chain. 

Takes P_WIN_SEND, returns STATUS. 

Comments clsChoice responds when pArgs->msg is msgButtonBeginPreview or msgButtonDone by using 

msgControlSetDirty(true) to mark its children as dirty. This is done as follows: 

clsChoice calls its ancestor and remembers the returned status. It then tests whether pArgs->msg is 
msgButtonDone. If so, then if one of the child buttons is currently previewing, clsChoice just returns 
the saved status (because it was when the previewing started that the choice marked its children as dirty). 
If, however, the msg is msgButtonDone and no button is previewing, the choice will go ahead and mark 
its children dirty (this case can happen if a child button is changing value programmatically and so isn't 
previewing), then return stsManagerContinue. 

If the pArgs->msg is msgButtonBeginPreview, the choice will mark its children dirty and then return 
stsManagerContinue. 

If the pArgs->msg is anything else, clsChoice will return the status saved from the call to its ancestor. 

Return Valye stsManagerContinue tell the caller to continue to propagate the msgWinSend 
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msgControlGetDirty 

Sets *pArgs true if any child control is dirty, false otherwise. 
Takes P_BOOLEAN, returns STATUS. 



msgControlGetEnable 

Sets *pArgs true if any child control is enabled, false otherwise. 
Takes P_BOOLEAN, returns STATUS. 



Comments 



msgControlGetValue 

Gets the tag of the child button that is currently on. 

Takes P_TAG, returns STATUS. 

Returns stsChoiceNoValue if no child button is on. 



msgControlSetDirty 

Forwards this message and pArgs on to each child control in the choice. 
Takes BOOLEAN, returns STATUS. 



msgControlSetEnable 

Forwards this message and pArgs on to each child control in the choice. 
Takes BOOLEAN, returns STATUS. 



Comments 



msgControlSetValue 

Turns on the child button having the passed tag. 

Takes TAG, returns STATUS. 

If another child button was on, it is turned off. 



msgTkTableAddAsFirst 

Adds specified window as the first child in the table. 

Takes WIN, returns STATUS. 

Comments clsChoice first calls its ancestor, then gets its manager via msgTkTableGetManager. If it has no 

manager, clsChoice returns stsOK. Otherwise, clsChoice gets the BUTTON_STYLE.on value of the new 
button and, if that is true, uses msgChoiceMgrSetOnButton to change the choice's 'on' button to the 
one just added. 

msgTkTableAddAsLast 

Adds specified window as the last child in the table. 

Takes WIN, returns STATUS. 

Comments clsChoice first calls its ancestor, then gets its manager via msgTkTableGetManager. If it has no 

manager, clsChoice returns stsOK. Otherwise, clsChoice gets the BUTTON_STYLE.on value of the new 
button and, if that is true, uses msgChoiceMgrSetOnButton to change the choice's 'on' button to the 
one just added. 
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msgTkTableAddAsSibling 

Inserts specified window in front of or behind an existing child. 

Takes P_TK_TABLE_ADD_SIBLING, returns STATUS. 

Comments clsChoice first calls its ancestor, then gets its manager via msgTkTableGetManager. If it has no 

manager, clsChoice returns stsOK. Otherwise, clsChoice gets the BUTTON_STYLE.on value of the new 
button and, if that is true, uses msgChoiceMgrSetOnButton to change the choice's 'on' button to the 
one just added. 

msgTkTableAddAt 8 

Inserts specified window table at specified index. 

Takes P_TK_TABLE_ADD_AT, returns STATUS. 

Comments clsChoice first calls its ancestor, then gets its manager via msgTkTableGetManager. If it has no 

manager, clsChoice returns stsOK. Otherwise, clsChoice gets the BUTTON_STYLE.on value of the new 
button and, if that is true, uses msgChoiceMgrSetOnButton to change the choice's 'on' button to the 
one just added. 

msgTkTableRemove 

Extracts pArgs from the table. 

Takes WIN, returns STATUS. 

Comments clsChoice first calls its ancestor, then gets its manager via msgTkTableGetManager. If it has no 

manager, clsChoice returns stsOK. Otherwise, clsChoice checks to see if the button being removed is 
the one that is currently 'on' (by sending msgChoiceMgrGetOnButton to its manager). If so, the choice 
will either set the manager's 'on' button to the first remaining child (if the button's 
BUTTON_STYLE. contact is bsContactLockOn), or to null (if no children remain or the button's 
BUTTON_STYLE.contact is anything else). Put simply, the choice repairs its state according to whether 
the choice is always exactly one value, or can have no value. 

msgTkTableChildDefaults 

Sets the defaults in P_ARGS for a common child. 

Takes P_UNKNOWN, returns STATUS. 

Comments This can be sent to either an instance of clsChoice or to clsChoice itself. Here is the response for either 

case: 

if <pArgs->object. class inherits from clsGWin> 
pArgs->gWin. style. gestureEnable = false; 

if <pArgs->object .class inherits from clsBorder> { 

pArgs->border. style. edge = bsEdgeNone; 

pArgs->border. style. topMargin = 1; 

pArgs->border.style.bottomMargin = 1; 
} 

if <pArgs->object. class inherits from clsLabel> 
pArgs->label . style . xAlignment = IsAlignLef t ; 
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if <pArgs->object. class inherits from clsButton> { 
pArgs->button. style. notifyDetail = true; 
pArgs->button. style. contact = bsContactLockOn; 
pArgs->button. style. feedback = bsFeedbackDecorate; 
pArgs->button . style . of f Decoration = 

lsDecorationExclusiveOff; 
pArgs->button . style . onDecoration = 

lsDecorationExclusiveOn; 
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See Also 



This file contains the API definition for clsCustomLayout. clsCustomLayout inherits from clsBorder. 

Provides container windows which position and size their child windows according to complex 
constraints you specify for each child. 

clsTableLayout 



Jfr Debugging Flags 

The clsCustomLayout debugging flag is 'W\ Defined values are: 
flagl (0x0002) msgWinLayoutSelfinfo 
You can also set the '%' flag to: 
flag8 (0x0100) layout timing 



tifndef CLAYOUT_INCLUDED 
tdefine CLAYOUT_INCLUDED 

tinclude <border.h> 



♦include <string.h> 



tifndef BORDER_INCLUDED 

tendif 

tifndef _STRING_H_INCLUDED 

tendif 



Common #defines and fypedels 



typedef OBJECT CSTM_LAYOUT; 

typedef struct CSTM_LAYOUT_STYLE { 

U16 limit ToRootWin : 1; // limit bounds to stay within theRootWindow 

U16 spare : 15; // unused (reserved) 
} CSTM_LAYOUT_STYLE, *P_CSTM_LAYOUT_STYLE; 

Default CSTM LAYOUT STYLE: 



limitToRootWin 



= false 



typedef struct CSTM_LAYOUT_METRICS { 

CSTM_LAYOUT_STYLE style; // overall style 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} CSTM_LAYOUT_METRICS, *P_CSTM_LAYOUT_METRICS; 

Constraints for Custom layout. For each of these, relWin of pNull and relWinTag of zero maps to 
parent. 

Enuml6(CSTM LAYOUT CONSTRAINT) { 



// for x, y, width, height 
clAsIs = 0, // 
clAbsolute =1, // 

// for x, y, width, height: 



clBefore 


= 2, 


// 
// 
// 


clSameAs 


= 3, 


// 


clAfter 


= 4, 


// 
// 


clPctOf 


= 5 


// 



x, y: leave unchanged; w, h: use desired size 
use absolute value specified in spec 

all relative to relWin 
clBefore clMinEdge is one pixel less than 
the border rect; clBefore clMaxEdge is 
on the border inner rect 
same as relWin 

clAfter clMaxEdge is one pixel after max edge 
clAfter clMinEdge is on the border inner rect 
value * relWin / 100 
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possible edge specifications 

tdefine clMinEdge // x: left edge, y: bottom edge 

tdefine clCenterEdge 1 // x, y: mid point 

tdefine clMaxEdge 2 // x: right edge, y: top edge 

tdefine clBaselineEdge 3 // x: horiz. baseline, y: vertical baseline 

macro for defining an x or y constraint to align two edges 

tdefine ClAlign(childEdge, constraint, relWinEdge) \ 

( ((childEdge) « 6) | ((relWinEdge) « 4) | (constraint) ) 

macro for defining a w or h constraint to extend to an edge 

tdefine ClExtend (constraint, relWinEdge) \ 
ClAlign(clMaxEdge, constraint, relWinEdge) 

can be or'ed into any constraint (except clAsIs or clAbsolute) to refer to opposite dimension. 

tdefine clOpposite flag8 

can be or'ed into any constraint to compute new value as Max(as-is value, constraint-computed value) 
useful for children which need to be at least their desired size, but can be bigger (e.g. extend to parent's 
edge) 

tdefine clAtLeastAsIs flag9 

can be or'ed into any constraint to compute new value as specified constraint or clAsIs if the custom 
layout window has wsShrinkWrapWidth/Height on. This allows a child to be shrink wrapped around if 
the custom layout window is computing its own size; or, for example, have the child's width extend to 
the edge of the parent if the parent is forced to a bigger size. 

tdefine clAsIsIfShrinkWrap flaglO 

can be or'ed into width or height constraint to exclude a child's width or height from the shrink-wrap 
computation. This is useful for children which align to parent's max edge and overlap other children. 

tdefine clShrinkWrapExclude flagll 

macros to extract the parts of a constraint 

tdefine ClChildEdge(c) (((c) » 6) & 0x3) 

tdefine CIRelWinEdge (c) (((c) » 4) & 0x3) 

tdefine CIConstraint (c) ((c) & 0x7) 

typedef struct CSTM_LAYOUT_DIMENSION { 
CSTM_LAYOUT_CONSTRAINT constraint; 

S32 value; // offset or absolute value 

WIN relWin; //. relative window 

U32 relWinTag; // tag of relative window 

U16 valueUnits : 6, // units for value (e.g. bsUnitsLayout) 

sparel : 10; // unused (reserved) 

U32 spare; // unused (reserved) 

} CSTM_LAYOUT_DIMENSION, *P_CSTM_LAYOUT_DIMENSION; 

typedef struct CSTM_LAYOUT_SPEC { 

CSTM_LAYOUT_DIMENSION x, y, w, h; 
} CSTM_LAYOUT_SPEC, *P_CSTM_LAYOUT_SPEC; 

typedef struct CSTM_LAYOUT_CHILD_SPEC { 

WIN child; 

CSTM_LAYOUT_SPEC metrics; 

BOOLEAN parent ShrinkWrapWidth; 

BOOLEAN parentShrinkWrapHeight; 

U32 spare; // unused (reserved) 

} CSTM LAYOUT CHILD SPEC, *P CSTM LAYOUT CHILD SPEC; 
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msgNew 

Creates a custom layout window. 

Takes P_CSTM_LAYOUT_NEW, returns STATUS. Category: class message. 

typedef CSTM_LAYOUT_METRICS CSTM_LAYOUT_NEW_ONLY, *P_CSTM_LAYOUT_NEW_ONLY; 
tdefine customLayoutNewFields \ 

borderNewFields \ 

CSTM_LAYOUT_NEW_ONLY customLayout ; 

Arguments typedef struct CSTM_LAYOUT_NEW { 

customLayoutNewFields 
} CSTM_LAYOUT_NEW, *P_CSTM_LAYOUT_NEW; 

msgNewDefaults 

Initializes the CSTM_LAYOUT_NEW structure to default values. 

Takes P_CSTM_LAYOUT_NEW, returns STATUS. Category: class message. 

Messsge typedef struct CSTM_LAYOUT_NEW { 

Arguments customLayoutNewFields 

} CSTM_LAYOUT_NEW, *P_CSTM_LAYOUT_NEW; 

Comments Zeroes out pNew->customLayout. 



Messocg© 
Arguments 



msgCstmLayoutGetMetrics 



Passes back the current metrics. 

Takes P_CSTM_LAYOUT_METRICS, returns STATUS. 

tdefine msgCstmLayoutGetMetrics MakeMsg(clsCustomLayout, 1) 

typedef struct CSTM_LAYOUT_METRICS { 

CSTM_LAYOUT_STYLE style; // overall style 
U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} CSTM LAYOUT METRICS, *P CSTM LAYOUT METRICS; 



msgCstmLayoutSetMetrics 

Sets the current metrics. 

Takes P_CSTM_LAYOUT_METRICS, returns STATUS. 

tdefine msgCstmLayoutSetMetrics MakeMsg(clsCustomLayout, 2) 

typedef struct CSTM_LAYOUT_METRICS { 

CSTM_LAYOUT_STYLE style; // overall style 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} CSTM_LAYOUT_METRICS, *P_CSTM_LAYOUT_METRICS; 

If style.limitToRootWin is changed, msgWinSetLayoutDirty(true) will be self-sent. 



Message 
Arguments 



Comments 



msgCstmLayoutGetStyle 

Passes back current style values. 

Takes P_CSTM_LAYOUT_STYLE, returns STATUS. 

tdefine msgCstmLayoutGetStyle MakeMsg(clsCustomLayout, 5) 
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Message typedef struct CSTM_LAYOUT_STYLE { 

Arguments U16 limitToRootWin : 1/ // limit bounds to stay within theRootWindow 

U16 spare : 15; // unused (reserved) 

} CSTM_LAYOUT_STYLE, *P_CSTM_LAYOUT_STYLE; 

msgCstmLayoutSetStyle 

Sets style values. 

Takes P_CSTM_LAYOUT_STYLE, returns STATUS. 
♦define msgCstmLayoutSetStyle MakeMsg(clsCustomLayout, 6) 
Comments If style.limitToRootWin is changed, msgWinSetLayoutDirty(true) will be self-sent. 

CstmLayoutSpecInit 

Zeros the P_CSTM_LAYOUT_SPEC. 

Returns VOID. 

#define CstmLayoutSpecInit (lm) memset((lm), 0, sizeof (CSTM_LAYOUT_SPEC) ) 

Messoge typedef struct CSTM_LAYOUT_STYLE { 

Argomesits U16 limitToRootWin : 1; // limit bounds to stay within theRootWindow 

U16 spare : 15; // unused (reserved) 

} CSTM_LAYOUT_STYLE, *P_CSTM_LAYOUT_STYLE; 

Comments This is equivalent to the following: 

x, y, w, h constraint = clAsIs 

You should use CustmLayoutSpecInit to initialize the layout spec that you pass in to 
msgCstmLayoutSetChildSpec. For example: 

CSTM_LAYOUT_CHILD_SPEC CS; 

CstmLayoutSpecInit (&cs .metrics) ; 

cs. child = child; 

cs. met rics.x. constraint = ClAlign(clMinEdge, clSameAs, clMinEdge); 

cs. met rics.y. constraint = ClAlign (clMinEdge, clSameAs, clMinEdge); 

Ob jCallRet (msgCstmLayoutSetChildSpec, clayout, &cs, s) ; 

msgCstmLayoutSetChildSpec 

Sets layout spec for given child. 

Takes P_CSTM_LAYOUT_CHILD_SPEC, returns STATUS. 

tdefine msgCstmLayoutSetChildSpec MakeMsg(clsCustomLayout, 3) 

fttessdge typedef struct CSTM_LAYOUT_CHILD_SPEC { 

Arguments WIN child; 

CSTM_LAYOUT_SPEC metrics; 

BOOLEAN parent ShrinkWrapWidth; 

BOOLEAN parent ShrinkWrapHeight; 

U32 spare; // unused (reserved) 

} CSTM_LAYOUT_CHILD_SPEC, *P_CSTM_LAYOUT_CHILD_SPEC; 

Comment* Storage will be allocated for the spec. The child spcecification will be used in response to 

msgCstmLayoutGetChildSpec, which is self-sent during msgWinLayoutSelf. 

clsCustomLayout will self-send msgWinSetLayoutDirty(true). 

See Also CstmLayoutSpecInit 
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msgCstmLayoutRemoveChildSpec 

Removes the spec for the specified child (pArgs). 

Takes WIN, returns STATUS. 

tdefine msgCstmLayoutRemoveChildSpec MakeMsg(clsCustomLayout, 7) 

Comments If a child is extracted or destroyed, and msgCstmLayoutSetChildSpec was used to set the child layout 

constraints, you must use this message to remove the child layout constraints. 

See Also msgCstmLayoutSetChildSpec 

msgCstmLayoutGetChildSpec 

Passes back the current spec for the specified child. 

Takes P_CSTM_LAYOUT_CHILD_SPEC, returns STATUS. Category: self-sent, subclass responsibility. 

#define msgCstmLayoutGetChildSpec MakeMsg(clsCustomLayout, 4) 

tdefine stsCstmLayoutBadRelWin MakeStatus(clsCustomLayout, 1) 

#define stsCstmLayoutBadRelWinTag MakeStatus (clsCustomLayout, 4) 

tdefine stsCstmLayoutLoop MakeStatus(clsCustomLayout, 2) 

tdefine stsCstmLayoutBadConstraint MakeStatus(clsCustomLayout, 3) 



rtesscsge 
irqiimersl 



Comments 



typedef struct CSTM_LAYOUT_CHILD_SPEC { 

WIN child; 

CSTM_LAYOUT_SPEC metrics; 

BOOLEAN parent ShrinkWrapWidth ; 

BOOLEAN parentShrinkWrapHeight; 

U32 spare; // unused (reserved) 

} CSTM_LAYOUT_CHILD_SPEC, *P_CSTM_LAYOUT_CHILD_SPEC; 

Self-sent during msgWinLayout to retrieve the current spec from subclasses. clsCustomLayout responds 
by returning the stored spec, or an initialized spec (CstmLayoutSpecInit()) if none is found. 

Subclasses can catch this message, look at pArgs->child and return the layout constraints for known 
children. 

If pArgs->relWin is not objNull, this uid will be used as the relative window. Otherwise, if 
pArgs->relWinTag will be used to find the relative window (i.e. relWinTag should be the window tag of 
the relative window). The relative window must be objNull (in which case the parent is used) or a 
sibling of pArgs->child. 

status values 



^Messages from other classes 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments clsCustomLayout will save the constraints for each child that has wsSendFile on in its 

WIN_METRICS.flags.style. If a child's constraint specifies a relWin that does not file, the relWin will be 
filed as objNull. 
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msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsCustomLayout will restore the constraints for each child that was filed. 

clsCustomLayout will self-send msgWinSetLayoutDirty(true) if the system font or system font scale 
changed since the table was filed. pArgs->pEnv is cast to a P_WIN_RESTORE_ENV and must be a valid 
window environment pointer. 

msgWinLayoutSelf 

Tell a window to layout its children (sent during layout). 
Takes P_WIN_METPJCS, returns STATUS. 
Comments clsCustomLayout responds by laying out its children. For each child, the following is done: 

♦ msgCstmLayoutGetChildSpec is self-sent with the following CSTM_IAYOUT_CHILD_SPEC 
parameters: 

child = child to be layed out; 

metrics = result of CstmLayoutSpecInit () ; 

parentShrinkWrapWidth = true if self can shrink wrap width; 

parent ShrinkWrapWidth = true if self can shrink wrap height; 

Self can shrink wrap width/height if pArgs->options has wsLayoutResizeon and sel fs 

WinShrinkWrapWidth/Height(WIN_METRICS.flags.style) is true. 

The passed-back pArgs will be used as the child's layout spec. 

♦ msgBorderGetOuterOffsets is sent to the child with a default pArgs (RECT32) of (1, 1, 1, 1). The 
outer offsets are used to define "after min edge" or "before max edge" constraints. 

♦ The x, y, w, h of the child is computed based on its constraints. If the either w or h constraints are 
clAsIs, msgWinGetDesiredSize is sent to the child to determine its desired size. 

If pArgs->options has wsLayoutResize on and self has shrink wrap width/height on, the bounding box 
around the layed out children will be computed and passed back in pArgs->bounds.size. If 
style.limitToRootWin is true, and self has no parent or selfs parent is theRootWindow, the computed 
size will be limited to insure that self will fit on theRootWindow and selfs origin may be altered (via 
msgWinDelta) to insure the window is fully on screen. 

Return ¥c»l»e stsCstmLayoutBadRelWin The relWin specified for a child spec was not the uid of a sibling window. 

stsCstmLayoutBadRelWinTag The relWinTag specified for a child spec was not the tag of a sibling 
window. 

stsCstmLayoutLoop The specified set of child constraints results in a circular layout loop. For 

example, child As width clSameAs child B's width and child B s width clSameAs child As width. 

stsCstmLayoutBadConstraint A constraint specified for a child is not a valid value. 
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CLOSEBOX.H 



This file contains the API definition for clsCloseBox. 

clsCloseBox inherits from clsMenuButton. 

Close boxes are frame decorations that let you close the frame. Close boxes paint as a triangle in the 
upper-left hand corner. 



#ifndef CLOSEBOX_INCLUDED 
♦define CLOSEBOX_INCLUDED 

tinclude <mbutton.h> 



#ifndef MBUTTONJENCLUDED 
tendif 



Common #defines and typedefs 



#define hlpCloseBoxGeneral MakeTag (clsCloseBox, 1) 
typedef OBJECT CLOSEJBOX; 
typedef struct CLOSE_BOX_STYLE { 

U16 spare : 16; // unused (reserved) 
} CLOSE BOX STYLE, *P CLOSE BOX STYLE; 



^Messages 



msgNew 

Creates a closebox window. 

Takes P_CLOSE_BOX_NEW, returns STATUS. Category: class message. 

Arguments typedef Struct CLOSE_BOX_NEW_ONLY { 

CLOSE_BOX_STYLE style; 

U32 spare; // unused (reserved) 

} CLOSE_BOX_NEW_ONLY, *P_CLOSE_BOX_NEW_ONLY; 

tdefine closeBoxNewFields \ 

menuButtonNewFields \ 

CLOSE_BOX_NEW_ONLY closeBox; 

typedef struct CLOSE_BOX_NEW { 

closeBoxNewFields 
} CLOSE BOX NEW, *P CLOSE BOX NEW; 



msgNewDefaults 

Initializes the CLOSE_BOX_NEW structure to default values. 

Takes P_CLOSE_BOX_NEW, returns STATUS. Category: class message. 

typedef struct CLOSE_BOX_NEW { 

closeBoxNewFields 
} CLOSE_BOX_NEW, *P_CLOSE_BOX_NEW; 

Zeroes out pArgs->closeBox and sets 

pArgs->win. flags. style &= ~(U32) (wsShrinkWrapWidth | wsShrinkWrapHeight) ; 



Messoge 
Arguments 



Comments 
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pArgs->gWin. style. gestureEnable = false; 
pArgs->gWin.helpId = hlpCloseBoxGeneral; 

pArgs->border. style. edge = bsEdgeBottom; 
pArgs->border. style. shadow = bsShadowNone; 
pArgs->border. style. join = bsJoinSquare; 
pArgs->border . style . lef tMargin = bsMarginNone; 
pArgs->border. style. rightMargin = bsMarginNone; 
pArgs->border.style.bottomMargin = bsMarginNone; 
pArgs->border.style.topMargin = bsMarginNone; 

pArgs->button. style. feedback = bsFeedbackNone; 



msgCloseBoxGetStyle 

Passes back the current style values. 

Takes P_CLOSE_BOX_STYLE, returns STATUS. 

♦define msgCloseBoxGetStyle MakeMsg(clsCloseBox, 1) 

Messog© typedef struct CLOSE_BOX_STYLE { 

Arguments U16 spare : 16; // unused (reserved) 

} CLOSE BOX STYLE, *P CLOSE BOX STYLE; 



msgCloseBoxSetStyle 

Sets the style values. 

Takes P_CLOSE_BOX_STYLE, returns STATUS. 

tdefine msgCloseBoxSetStyle MakeMsg(clsCloseBox, 2) 

Aessoge typedef struct CLOSE_BOX_STYLE { 

l,rg«meRfs U16 spare : 16; // unused (reserved) 

} CLOSE BOX STYLE, *P CLOSE BOX STYLE; 
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CMDBAR.H 



This file contains the API definition for clsCommandBar. 

clsCommandBar inherits from clsTkTable. 

Command bars are tkTables of buttons used in option sheets and frames. 



#ifndef CMDBAR_INCLUDED 
#define CMDBAR_INCLUDED 

#include <tktable.h> 



#ifndef TKTABLE_INCLUDED 
tendif 



Common #defines and typedef s 



typedef OBJECT COMMAND_BAR; 
typedef struct COMMAND_BAR_STYLE { 

U16 spare : 16; // unused (reserved) 
} COMMAND BAR STYLE, *P COMMAND BAR STYLE; 



F Messages 



msgNew 

Creates a command bar window. 

Takes P_COMMAND_BAR_NEW, returns STATUS. Category: class message. 

Arguments typedef Struct COMMAND_BAR_NEW_ONLY { 

COMMAND_BAR_STYLE style; // overall style 

U32 spare; // unused (reserved) 

} COMMAND_BAR_NEW_ONLY, *P_COMMAND_BAR_NEW_ONLY; 

tdefine commandBarNewFields \ 
tkTableNewFields \ 

COMMAND_BAR_NEW_ONLY commandBar; 

typedef struct COMMAND_BAR_NEW { 

commandBarNewFields 
} COMMAND BAR NEW, *P COMMAND BAR NEW; 



Messoge 
Arguments 



Comments 



msgNewDefaults 

Initializes the COMMAND_BAR_NEW structure to default values. 

Takes P_COMMAND_BAR_NEW, returns STATUS. Category: class message. 

typedef struct COMMAND_BAR_NEW { 

commandBarNewFields 
} COMMAND BAR NEW, *P COMMAND BAR NEW; 



Sets 



pArgs->gWin. style. gestureEnable = false; 
pArgs->border. style. backgroundlnk = bsInkGray33; 
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pArgs->border . style . topMargin = bsMarginMedium; 
pArgs ->border . style . bott omMargin = bsMarginMedium; 
pArgs->border.style.leftMargin = bsMarginSmall; 
pArgs->border.style.rightMargin = bsMarginSmall; 

pArgs->tableLayout . style . tblXAlignment = tlAlignCenter; 
pArgs->tableLayout . style . tblYAlignment = tlAlignCenter; 
pArgs->tableLayout. style. childXAlignment = tlAlignCenter; 
pArgs->tableLayout.style.childYAlignment = tlAlignCenter; 
pArgs->tableLayout. style. growChildWidth = false; 
pArgs->tableLayout. style. growChildHeight = true; 

pArgs->tableLayout.numCols. constraint = tllnfinite; 
pArgs->tableLayout.numRows. constraint = tlAbsolute; 
pArgs->tableLayout.numRows. value = 1; 
pArgs->tableLayout.colWidth. constraint = tlGroupMax; 
pArgs->tableLayout.colWidth.gap = defaultColGap; 
pArgs->tableLayout.rowHeight. constraint = tlChildrenMax; 
pArgs->tableLayout .rowHeight .gap = 0; 

Alters pArgs->tkTable.pButtonNew as in msgTkTableChildDefaults. 



msgCommandBarGetStyle 

Passes back the current style values. 

Takes P_COMMAND_BAR_STYLE, returns STATUS. 

♦define msgCommandBarGetStyle MakeMsg(clsCommandBar, 1) 

Messoge typedef struct COMMAND_BAR_STYLE { 

Arguments U16 spare : 16; // unused (reserved) 

} COMMAND BAR STYLE, *P COMMAND BAR STYLE; 



msgCommandBarSetStyle 

Sets the style values. 

Takes P_COMMAND_BAR_STYLE, returns STATUS. 

#define msgCommandBarSetStyle MakeMsg(clsCommandBar, 2) 

sage typedef Struct COMMAND_BAR_STYLE { 

tments U16 spare : 16; // unused (reserved) 

} COMMAND_BAR_STYLE, *P_COMMAND_BAR_STYLE ; 

Messages from Other Classes 

msgTkTableChildDefaults 

Sets the defaults in pArgs for a common child. 
Takes P_UNKNOWN, returns STATUS. 
clsCommandBar sets up defaults for each child as follows: 
If the child is a descendant of clsGWin, then 

pArgs->gWin. style. gestureEnable = false; 
If the child is a descendant of clsButton, then 

pArgs->butt on. style. feedback = bsFeedback3D ; 
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CONTROL.H 



This file contains the API definition for clsControl. 

clsControl inherits from clsBorder. 

clsControl implements the previewing and client notification behavior of several UI components. 
clsControl is an abstract class ~ it is never instantiated directly. 



Debugging Flags 



The clsControl debugging flag is '%'. Defined values are: 
flag8 (0x0100) msgControlEnable info 

♦ifndef CONTROL_INCLUDED 
♦define CONTROL_INCLUDED 

♦include <border.h> 



♦ifndef BORDER_INCLUDED 
#endif 



Common #defines and typedefs 



typedef OBJECT 



CONTROL; 



Dynamic Enable Styles 

Use one of these values in control's style. dynamicEnable. 



♦define csDynamicNone 

♦define csDynamicClient 1 

♦define csDynamicObject 2 

♦define csDynamicPargs 3 

typedef struct CONTROL STYLE { 



U16 enable 

previewGrab 

previewRepeat 

previewing 

dirty 

previewEnable 

showDirty 

dynamicEnable 

privatel 

spare 



1, 
1, 
1, 
1, 
1, 
1, 
1, 
2, 
1, 
6; 



// 
// 
// 
// 

// 
// 
// 
// 
// 
// 
// 
// 
// 
// 



no dynamic determination of "enabled" 
send msgControlProvideEnable to client 
send msgControlProvideEnable to "object" 
set "enabled" from pArgs 

if enabled, a control responds to input 

grab input when previews start 

previews repeat on time-out 

msgControlBeginPreview has been sent out 

dirty status 

self -send msgControlBeginPreview, etc. 

visuals reflect dirty state 

how "enable" value is determined 

reserved 

unused (reserved) 



} C0NTR0L_STYLE, *P_C0NTR0L_STYLE ; 
Default CONTROL STYLE: 



enable 


= true 


previewGrab 


= true 


previewRepeat 


= false 


previewing 


= false 


dirty 


= false 


previewEnable 


= false 


showDirty 


= true 
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typedef struct CONTROL_STRING { 

P_CHAR pString; 

U16 len; 

U32 spare; // unused (reserved) 

} CONTROL STRING, *P CONTROL STRING; 



Advisory return values for subclasses 

♦define stsControlCancelPreview 
#define stsControlCancelRepeat 



MakeWarning(clsControl, 13) 
MakeWarning(clsControl, 1) 



msgNew 

Creates a control window. 

Takes P_CONTROL_NEW, returns STATUS. Category: class message. 

Arguments typedef Struct CONTROL_NEW_ONLY { 

CONTROL_STYLE style; // overall style 

OBJECT client; // client to notify 

U32 spare; // unused (reserved) 

} CONTROL_NEW_ONLY, CONTROL_METRICS, 

*P_CONTROL_NEW_ONLY, *P_CONTROL_METRICS; 
tdefine controlNewFields \ 

borderNewFields \ 

CONTROL_NEW_ONLY control; 

typedef struct CONTROL_NEW { 

controlNewFields 
} CONTROL_NEW, *P_CONTROL_NEW; 

Comments Note that setting pArgs->control.style.enable to false does not result in pArgs->border.style.look set to 

bsLooklnactive. If you change style.enable after msgNew (via msgControlSetStyle or 
msgControlSetEnable), the border.style.look will be changed to match. 



Message 
Argymertfs 



Comments 



msgNewDefaults 

Initializes the CONTROL_NEW structure to default values. 

Takes P_CONTROL_NEW, returns STATUS. Category: class message. 

typedef struct CONTROL_NEW { 

controlNewFields 
} CONTROL_NEW, *P_CONTROL_NEW; 

Zeroes pArgs->control and sets 

pArgs->win. flags. style |= wsFilelnline; 

pArgs->border.style.previewAlter = bsAlterBackground; 
pArgs->border. style. selectedAlter = bsAlterBackground; 

pArgs->control. style. enable = true; 
pArgs->control< style. showDirty ■ true; 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments If the client of the control is OSThisAppO, this is remembered and reinstated in msgRestore. In any 

case, the client is not saved. 
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msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsControl restores the instance from the file. If the client of the control was OSThisAppO when filed, 

the client is set to OSThisAppO, otherwise objNull. 



|F Messages Clients Send to Controls 



msgControlGetMetrics 



Passes back the current metrics. 

Takes P_CONTROL_METRICS, returns STATUS. 

♦define msgControlGetMetrics MakeMsg (clsControl, 1) 



msgControlSetMetrics 



Sets the metrics. 

Takes P_CONTROL_METRICS, returns STATUS. 

♦define msgControlSetMetrics MakeMsg (clsControl, 2) 



Message 
Arguments 



msgControlGetStyle 

Passes back the current style values. 

Takes P_CONTROL_STYLE, returns STATUS. 

♦define msgControlGetStyle MakeMsg (clsControl, 3) 



typedef struct CONTROL STYLE { 



6 enable 


1, 


// 


previewGrab 


1, 


// 


previewRepeat 


1, 


// 


previewing 


1, 


// 


dirty 


1, 


// 


previewEnable 


1, 


// 


showDirty 


1, 


// 


dynamicEnable 


2, 


// 


private 1 


1, 


// 


spare 


6; 


// 



if enabled, a control responds to input 

grab input when previews start 

previews repeat on time-out 

msgControlBeginPreview has been sent out 

dirty status 

self -send msgControlBeginPreview, etc. 

visuals reflect dirty state 

how "enable" value is determined 

reserved 

unused (reserved) 



} CONTROL STYLE, *P CONTROL STYLE; 



tessoge 
trguments 



msgControlSetStyle 

Sets the style values. 

Takes P_CONTROL_STYLE, returns STATUS. 

tdefine msgControlSetStyle MakeMsg (clsControl, 4) 



typedef struct CONTROL STYLE { 



U16 enable 


1, 


// 


previewGrab 


1, 


// 


previewRepeat 


1, 


// 


previewing 


1, 


// 


dirty 


1, 


// 


previewEnable 


1, 


// 


showDirty 


1, 


// 


dynamicEnable 


2, 


// 


privatel 


1, 


// 


spare 


6; 


// 



if enabled, a control responds to input 

grab input when previews start 

previews repeat on time-out 

msgControlBeginPreview has been sent out 

dirty status 

self -send msgControlBeginPreview, etc. 

visuals reflect dirty state 

how "enable" value is determined 

reserved 

unused (reserved) 



} CONTROL STYLE, *P CONTROL STYLE; 
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Comments If style.enable changes, the control does the following: 

♦ self-sends msgBorderSetLook, with pArgs of bsLookActive if style.enable is true, bsLooklnactive 

otherwise. 

♦ self-sends msgControlCancelPreview, pNull if style.enable is false. 

msgControlGetClient 

Passes back metrics.client. 

Takes P_UID, returns STATUS. 

♦define msgControlGetClient MakeMsg(clsControl, 5) 

msgControlSetClient 

Sets metrics.client. 

Takes UID, returns STATUS. 

#define msgControlSetClient MakeMsg(clsControl, 6) 

msgControlGetDirty 

Passes back true if the control has been altered since dirty was set false. 

Takes P_BOOLEAN, returns STATUS. 

#define msgControlGetDirty MakeMsg(clsControl, 15) 

msgControlSetDirty 

Sets style.dirry. 

Takes BOOLEAN, returns STATUS. 

#define msgControlSetDirty MakeMsg(clsControl, 16) 

msgControlGetEnable 

Passes back style.enable. 

Takes P_BOOLEAN, returns STATUS. 

♦define msgControlGetEnable MakeMsg(clsControl, 17) 

msgControlSetEnable 

Sets style.enable. 

Takes BOOLEAN, returns STATUS. 

♦define msgControlSetEnable MakeMsg(clsControl, 18) 

Comments Responds to changes in style.enable as in msgControlSetStyle. 

msgControlEnable 

The control re-evaluates whether it is enabled. 

Takes P_CONTROL_ENABLE, returns STATUS. 

♦define msgControlEnable MakeMsg(clsControl, 19) 
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Subclass Responsibility Messages 

Arguments typedef struct CONTROL_ENABLE { 

WIN root; // In: originator 

OBJECT object; // In: object for msgControlProvideEnable 

BOOLEAN enable; // In: value to use iff csDynamicPargs 

U32 spare; // reserved (unused) 

} CONTROL_ENABLE, *P_CONTROL_ENABLE; 

Comments This is commonly used with menu buttons that need to be enabled/disabled according to some 

constraints known to the sender. For example, clsMenuButton sends msgControlEnable to its menu 
before showing the menu, which results in each control in the menu receiving msgControlEnable with 
appropriate parameters. See msgMenuButtonShowMenu (mbutton.h) for sample usage. 

clsControl responds to msgControlEnable as follows: O 

♦ If style.dynamicEnable is csDynamicNone, simply returns stsOK. 

♦ If style.dynamicEnable is csDynamicPargs, style.enable is set to pArgs->enable. 

♦ If style.dynamicEnable is csDynamicClient and metrics. client is objNull, does not change enable 
and returns stsOK. 

♦ If style.dynamicEnable is csDynamicObject and pArgs->object is objNull, sets style.enable to false 
(as in msgControlSetEnable) and returns stsOK. 

The cases that remain are style.dynamicEnable of csDynamicClient or csDynamicObject, and a 
non-null object. 

♦ If the object is not owned by OSThisProcess(), sets style.enable to false (as in 
msgControlSetEnable) and returns stsOK. Otherwise, sends msgControlProvideEnable with the 
following CONTROL_PROVIDE_ENABLE parameters: 

root = pArgs->root; 

control = self; 

tag = self's WINJMETRICS.tag; 

enable = current value of style.enable; 

♦ If the object responds to msgControlProvideEnable with stsNotUnderstood, sets style.enable to 
true (as in msgControlSetEnable) and returns stsOK. Otherwise, sets style.enable to 
CONTROL_PROVIDE_ENABLE. enable (as in msgControlSetEnable) and returns stsOK. 

See Also msgControlProvideEnable 

Subclass Responsibility Messages 

msgControlGetValue 

Passes back the current "value" of the control. 
Takes P_S32 , returns STATUS. 

#define msgControlGetValue MakeMsg (clsControl, 7) 

Comments In response to this message clsControl returns stsNotUnderstood. 

msgControlSetValue 

Sets the current "value" of the control. 

Takes S32 , returns STATUS. 

tdefine msgControlSetValue MakeMsg (clsControl, 8) 

In response to this message clsControl returns stsNotUnderstood. 
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Messages Controls Send to Self 



msgControlBeginPreview 

Self-sent when msgPenDown is received. 
Takes P_INPUT_EVENT, returns STATUS. Category: self-sent. 
#define msgControlBeginPreview MakeMsg (clsControl, 10) 

Comments clsControl responds with stsOK. pArgs is pNull if the preview is not caused by an input event. 

msgControlUpdatePreview 

Self-sent when msgPenMoveDown is received. 

Takes P_INPUT_EVENT, returns STATUS. Category: self-sent, 
tdefine msgControlUpdatePreview MakeMsg (clsControl, 11) 

Comments clsControl responds with stsOK. pArgs is pNull if the preview is not caused by an input event. 

msgControlRepeatPreview 

Self-sent if style.repeatPreview is true. Initial delay is 600ms, then immediate repeat until msgPenUp. 
Takes P_INPUT_EVENT, returns STATUS. Category: self-sent, 
tdefine msgControlRepeatPreview MakeMsg (clsControl, 12) 

Comments clsControl responds with stsOK. 

Subclasses can return stsControlCancelRepeat to prevent the next msgControlRepeatPreview. 
pArgs is pNull if the preview is not caused by an input event. 

msgControlCancelPreview 

Self-sent when style.previewGrab is false and msgPenExitDown is received. Clients or subclasses can 
send this to a control to cancel existing preview. 

Takes P_INPUT_EVENT, returns STATUS. Category: self-sent. 

#define msgControlCancelPreview MakeMsg (clsControl, 13) 

Comments Sets style.previewing to false. 

pArgs is pNull if the preview is not caused by an input event. 

msgControlAcceptPreview 

Self-sent when msgPenUp is received. 
Takes P_INPUT_EVENT, returns STATUS. Category: self-sent, 
tdefine msgControlAcceptPreview MakeMsg (clsControl, 14) 

Comments If gestures are enabled this message is not sent until msgGWinGesture is received with xgslTap. 

clsControl responds with stsOK. 
pArgs is pNull if the preview is not caused by an input event. 
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Messages Defined by Other Classes 



i Messages Controls Send to Client 



msgControlProvideEnable 

Sent out to client or "object" during processing of msgControlEnable. 

Takes P_CONTROL_PROVIDE_ENABLE, returns STATUS. 

#define msgControlProvideEnable MakeMsg (clsControl, 20) 

Arguments typedef struct CONTROL_PROVIDE_ENABLE { 

WIN root; // In: originator 

CONTROL control; // In: sending control O 

TAG tag; // In: tag of sending control 2 

BOOLEAN enable; // In/Out: enabled value for control 

U32 spare; // unused (reserved) 

} CONTROL PROVIDE ENABLE, *P CONTROL PROVIDE ENABLE; 



Messages Defined by Other Classes 



msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments clsControl first calls ancestor, then responds as follows. (In each of these cases, see below for status 

return value.) 

♦ If pArgs->flags has evBorderTaken set (see border.h), assumes clsBorder used the event and returns 
status. 

♦ If style.enable is false, or style.previewEnable is false, or the event is not a pen event, returns status 
returned by ancestor. 

♦ If pArgs->devCode is msgPenDown, self-sends msgControlBeginPreview passing along pArgs. If 
return status is stsControlCancelPreview, returns status. If style.previewRepeat is true, and return 
status is not stsControlCancelRepeat, the control repeats preview after 600ms delay. Sets 
style.previewing to true. 

♦ If pArgs->devCode is msgPenMoveDown, self-sends msgControlUpdatePreview passing along 
pArgs. If return status is stsControlCancelPreview, sets style.previewing to false and returns status. 

♦ If pArgs->devCode is msgPenUp, checks GWIN_STYLE.gestureEnable. If true, does nothing and 
returns status. Otherwise, self-sends msgControlAcceptPreview passing along pArgs and returns 
stsInputTerminate. 

♦ If pArgs->devCode is msgPenExitDown and style.previewGrab is true or style.previewing is false or 
GWIN_STYLE.gestureEnable is true, does nothing and returns status. Otherwise, self-sends 
msgControlCancelPreview passing along pArgs and returns stsInputTerminate. 

clsControl returns stsInputGrabTerminate if no error was encountered and style.previewing and 
style.previewGrab are true after processing the input event. Otherwise, the status returned by 
ObjectCallAncestorQ is returned. 
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msgGWinGesture 

Called to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

Comments If ObjectCallAncestor() returns stsOK, clsControl self-sends msgControlCancelPreview and returns 

stsOK. 

If pArgs->msg is xgslTap and style.previewEnable is true, self-sends msgControlAcceptPreview and 
returns stsOK. 

All other gestures result in msgGWinForwardedGesture to the control client, followed by 
msgControlCancelPreview to self. 

msgGWinAbort 

Clears the translation state of the GWin. 

Takes void, returns STATUS. 

Comments clsControl responds to this by self-sending msgControlCancelPreview if the receiver is currently 

previewing. 

msgGWinGestureDone 

Sent to signal the end of a gesture. 

Takes P_GWIN_GESTURE, returns STATUS. Category: self-sent. 

Comments clsControl responds to this by self-sending msgControlCancelPreview if the receiver is currently 

previewing. 

msgBorderGetDirty 

Passes back true if any child responds to msgBorderGetDirty with true; otherwise passes back false. 

Takes P_BOOLEAN, returns STATUS. 

Comments clsControl responds by self-sending msgControlGetDirty. If the control is dirty, true is passed back. 

Otherwise, this message is passed on to clsControl's ancestor. clsBorder will respond by passing back 
true if any child of this control is dirty. 

msgBorderSetDirty 

Sends msgBorderSetDirty(pArgs) to each child. 

Takes BOOLEAN, returns STATUS. 

Comments clsControl will call ancestor (to allow clsBorder to dirty any children), then self-send 

msgControlSetDirty(pArgs) . 
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COUNTER.H 



This file contains the API definition for clsCounter. 

clsCounter inherits from clsTableLayout. 

Counters are general components which display a current count and provide up/down arrows for the 
user to alter the count. 

Counters are used as notebook frame decorations to provide up/down arrows to move between pages. 



♦ifndef COUNTER_INCLUDED 
♦define COUNTER_INCLUDED 

♦include <t layout. h> 



♦ifndef TLAYOUT_INCLUDED 
♦endif 



Common #defines and typedefs 



♦define tagCounterDecArrow 
♦define tagCounterLabel 
♦define tagCounterlncArrow 

♦define hlpCounterDecArrow 
♦define hlpCounterLabel 
♦define hlpCounterlncArrow 

typedef OBJECT COUNTER; 



MakeTag ( cl sCounter , 1 ) 
MakeTag ( cl sCounter , 2 ) 
MakeTag (clsCounter, 3) 

t agCoun t e rDe c Ar row 

tagCounterLabel 

tagCounterlncArrow 



Show Style 



♦define csShowCount 

♦define csShowCountSlashTotal 1 

♦define csShowCountOf Total 2 
typedef struct COUNTER STYLE { 



// show "count" only (e.g. "24") 
// show "count /total" (e.g. "1/24") 
// show "count of total" (e.g. "1 of 24") 



U16 numCols 
show 
spare 



4, // number of columns for shrink-wrap 

3, // what to show 

9; // unused (reserved) 



} COUNTER STYLE, *P COUNTER STYLE; 



Messages 



Arguments 



msgNew 

Creates a counter window. 

Takes P_COUNTER_NEW, returns STATUS. Category: class message. 



typedef struct COUNTER_NEW_ONLY { 

COUNTER_STYLE style; 

OBJECT client ; 

S32 value; 

S32 total; 

U32 spare 1; 

U32 spare2; 



// client to notify 

// initial count 

// total to display 

// unused (reserved) 

// unused (reserved) 



} COUNTER NEW ONLY, *P COUNTER NEW ONLY; 
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♦define counterNewFields \ 
tableLayoutNewFields \ 
COUNTER_NEW_ONLY counter; 

typedef struct COUNTER_NEW { 

counterNewFields 
} COUNTER NEW, *P COUNTER NEW; 



Messoge 
Arguments 



Comments 



msgNewDefaults 

Initializes the COUNTER_NEW structure to default values. 

Takes P_COUNTER_NEW, returns STATUS. Category: class message. 

typedef struct COUNTER_NEW { 

counterNewFields 
} COUNTER NEW, *P COUNTER NEW; 



Zeroes out pArgs->counter and sets 

pArgs->border . style . lef tMargin 
pArgs->border . style . rightMargin 
pArgs->border . style .bottomMargin 
pArgs->border . style . topMargin 



= bsMarginNone; 
= bsMarginNone; 
= bsMarginSmall; 
= bsMarginMedium; 



pArgs->tableLayout. style. growChildWidth = false; 

pArgs->tableLayout. style. growChildHeight = false; 

pArgs->counter. style. numCols = 1; 
Default COUNTER STYLE: 



numCols 
show 



= 1 

= csShowCount 



Message 
Arguments 



msgCounterGetStyle 

Passes back the current style values. 

Takes P_COUNTER_STYLE, returns STATUS. 

♦define msgCounterGetStyle MakeMsg(clsCounter, 1) 

typedef struct COUNTER STYLE { 



U16 numCols 
show 
spare 



4, // number of columns for shrink-wrap 

3, // what to show 

9; // unused (reserved) 



} COUNTER STYLE, *P COUNTER STYLE; 



Message 
Arguments 



Comments 



msgCounterSetStyle 

Sets the style values. 

Takes P_COUNTER_STYLE, returns STATUS. 

♦define msgCounterSetStyle MakeMsg(clsCounter, 2) 

typedef struct COUNTER STYLE { 



U16 numCols 
show 
spare 



4, // number of columns for shrink-wrap 

3, // what to show 

9; // unused (reserved) 



} COUNTER_STYLE, *P_COUNTER_STYLE; 

If style.numCols requires the counter to be wider, clsCounter will self-send msgWinLayout to relayout. 
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msgCounterGetClient 



Passes back the current counter client. 

Takes PJDBJECT, returns STATUS. 

♦define msgCounterGetClient MakeMsg(clsCounter, 7) 



msgCounterSetClient 

Sets the client. 

Takes OBJECT, returns STATUS. 

♦define msgCounterSetClient 



MakeMsg(clsCounter, 8) 



Comments 



msgCounterGetValue 

Passes back the current count value. 
Takes P_S32, returns STATUS. 
♦define msgCounterGetValue 



MakeMsg(clsCounter, 3) 



msgCoutiterSetValue 

Sets the current counter value. 

Takes S32, returns STATUS. 

♦define msgCounterSetValue MakeMsg (clsCounter, 4) 

If the new value requires the counter to be wider, clsCounter will self-send msgWinLayout to relayout. 



MakeMsg(clsCounter, 11) 



msgCounterGetTotal 

Passes back the current total value. 
Takes P_S32, returns STATUS. 

♦define msgCounterGetTotal 

msgCounterSefTotal 

Sets the current total value. 

Takes S32, returns STATUS. 

♦define msgCounterSetTotal MakeMsg (clsCounter, 12) 

Comments ' If the new total value requires the counter to be wider, clsCounter will self-send msgWinLayout to 

relayout. 



Comments 



msgCounterlncr 

Increments the current counter value by adding in pArgs. 

Takes S32, returns STATUS. 

♦define msgCounterlncr MakeMsg (clsCounter, 5) 

If the new value requires the counter to be wider, clsCounter will self-send msgWinLayout to relayout. 
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msgCounterGoto 

Sends msgCounterNotify to the counter's client to alter the counter's value. 

Takes S32, returns STATUS. 

#define msgCounterGoto MakeMsg(clsCounter, 9) 

clsCounter will send msgCounterNotify to the counter's client with the following COUNTER_NOTIFY 
parameters: 



counter 


= self; 


initValue 


= current counter value; 


action 


= csActionAccept; 


value 


= pArgs; 



The client can alter the value parameter to goto a different value, if desired. 

A common use for this message is to create a menu with individual menu buttons representing 
particular counter values, and set the (msg, data) pair for each menu button to be (msgCounterGoto, 
desired value) and set the menu button's client to be the counter. 

msgCounterGetLabel 

Passes back the counter label window uid. 

Takes P_WIN, returns STATUS. 

tdefine msgCounterGetLabel MakeMsg (clsCounter, 10) 

Comments The label is an instance of clsMenuButton, and can be given a menu by setting the 

CONTROL_STYLE.previewEnable to true and using msgMenuButtonSetMenu. 

Messages Counters Send to Clients 

msgCounterNotify 

Sent to the client when an arrow repeats, finishes or cancels. 

Takes P_COUNTER_NOTIFY, returns STATUS. Category: client notification. 

#define msgCounterNotify MakeMsg (clsCounter, 6) 

Arguments Enuml6 (COUNTER_ACTION) { 

csActionlncrement = 0, // increment the counter 

csActionDecrement =1, // decrement the counter 

csActionCancel =2, // cancel the increment /decrement 

csActionAccept =3, // accept the increment /decrement 

}; 
typedef struct COUNTER_NOTIFY { 

OBJECT counter; // in: counter calling out 

S32 initValue; // in: initial value before repeat 

COUNTER_ACTION action; // in: what happened 

S32 value; // in/out: current value 

S32 total; // in: current total value 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} COUNTER_NOTIFY, *P_COUNTER_NOTIFY; 

Comments If the user presses or continues to hold down on the decrement arrow, pArgs->action will be set to 

csActionDecrement. 
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Messages Counters Send to Clients 

If the user presses or continues to hold down on the increment arrow, pArgs->action will be set to 
csActionlncrement. 

If the user pen's-up over either arrow, pArgs->action will be set to csActionAccept. 

If the user drags out of either arrow, pArgs->action will be set to csActionCancel. 

For any action, pArgs->value will be the current value of the counter and pArgs->initValue will be the 
initial value of the counter when the first csActionlncrement/Decrement was sent out. 

Clients should change pArgs->value to the new desired value. Note that clsCounter does not change the 
value of the counter, other than copying back pArgs->value. 

6 

If pArgs->value is not changed by the client, the value of the counter will not be changed. This allows O 

clients to use msgCounterlncr or msgCounterSetValue to alter the value during msgCounterNotify. 
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This file contains the API definition for clsField 

clsField inherits from clsLabel. 

Implements the UI component to edit, validate and display string data. 

Fields implement the basic UI component to edit simple strings of text. The user-interface for fields has 
been optimized for simple short one row strings of text, although they will function for multiple lines. 
All display information for translated fields is handled in clsLabel. Typically the label layout is fixed, and 
shrink wrap will be turned off in the label. Otherwise the field size will change as the value of the string 
changes, and lead to strange results and behavior. There are three basic User-Interfaces supported 
through the API to edit fields. These are defined in field.style.editType. 

Fields with editType of fstlnline support direct writing, appending, and a number of gestural editing 
operations, including bringing up an IP. Fields with editType of fstPopUp will only allow editing 
through an IP. Fields with editType of fstOverWrite make the field combed and allow over-writing on 
individual characters. These fields have very precise stroke targetting due to the character box 
constraints. This, in combination with only allowing three editing gestures (insert space, delete range, 
and delete character) allows for highly accurate handwriting and gesture recognition and for quick 
correction of mistakes. The down side of this style of field is that a specific UI look is implied. 

To further increase recognition accuracy, fields require a translator for both inline editing and in the IP. 
Translators have a rich API to provide various types of contextual information. This greatly increases 
translation accuracy. See msgNew, msgFieldGetXlate, msgFieldSetXlate, msgFieldCreateTranslator. 

Fields can also be run in delayed mode. Delayed fields allow the user to write into an empty field, and 
not translate the strokes on pen out of proximity. Delayed fields are translated when 
msgFieldTranslateDelayed is sent to the field. See msgFieldTranslateDelayed, 
msgFieldSetDelayScribble, and msgFieldGetDelayScribble for more information. 

Fields will replace newLines with spaces, and will strip trailing spaces when their value is retrieved. The 
value should be set via msgLabelSetString and retrieved via msgLabelGetString. 

Messages from clslnput, messages from clsGWin (other then msgGWinGesture), messages from 
clsWin, messages from clsLabel, messages from clsSelection, messages from clsXfer, messages from 
xlate, and messages from clsTracker should NOT be overridden by subclasses of clsField. 

Finally, fields provide simple hooks to allow clients or subclasses to perform various validation according 
to a common protocol. See msgFieldValidate for details. 

tifndef FIELD_INCLUDED 
#define FIELD_INCLUDED 

tifndef GO_INCLUDED 

tinclude <go.h> 

#endif 

tifndef LABEL_INCLUDED 

tinclude <label.h> 

tendif 

tifndef XTEMPLT_INCLUDED 

tinclude <xtemplt.h> 

tendif 

// Next Up: 31 Recycled: 28 
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Common #defines and fypedefs 

typedef OBJECT FIELD; 

Field Editing Types 

These define the types of edit User-Interface the field provides, defining the behavior of the field. These 
are used for style.editType. 

♦define fstlnline 1 // Direct editing on field, or through IP 

#define fstPopUp 2 // Editing only through an IP 

♦define fstOverWrite 3 // Editing in combed overwrite field 

Insertion Pad Types 

These define the type of Insertion Pad that will be created in msgFieldCreatePopUp when the type 
parameter is fipReplaceAll. Note: A call to msgFieldCreatePopUp when the type parameter is fiplnsert 
will look at the system preferences to determine the type of IP. These are used for style.popUpType. 

//♦define fstEditBox 1 // Obsolete 

♦define fstCharBox 2 // The pop-up is an ipsCharBox IP 

♦define fstCharBoxButtons 2 // Obsolete 

Character Box Memory 

For fstOverWrite fields, this defines the number of characters that should be used sent to the translator 
via msgXlateCharMemorySet. This causes the translator to cycle through choices and not return the 
same character from a translation. These are use for style.boxMemory. 

♦define fstBoxMemoryZero // Box memory is zero characters 
♦define fstBoxMemoryOne 1 //Box memory is one character 

♦define fstBoxMemoryFour 2 // Box Memory is four characters 

Selection/Input Target 

These define the interaction the field should have with both the selection manager and the input target 
when: 

- msgFieldKeyboardActivate is called 

- the pen is interacting with the field 

- msgFieldTranslateDelayed is called 

- the field is the recipient of a move/copy operation 
These are used for style.focusStyle. 

♦define fstlnputSelection 1 // Field takes selection and input target 

♦define fst Input 2 // Field takes input target only 

♦define fstNone 3 // Field takes neither selection nor target 

Upper Case Writer Rules 

These define the capitalization heuristic rules used by the field translator. These rules do not apply when 
the translator is provided by the client of the field, or the writer is not an all-caps writer. These are used 
for style.capOutput. 

♦define fstCapAsIs 1 

♦define fstCapFirstWord 2 

♦define fstCapAHWords 3 

♦define fstCapAll 4 
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Translator Type 

These define the type of translator given to and maintained by the field, and affects the parameters to 
msgFieldGetTranslator and msgFieldSetTranslator, the interaction with msgFieldCreateTranslator, 
and msgNew. See these messages for more information. These are used for style.xlateType. 

#define fstXlateObject 
#define fstXlateTemplate 1 

Field Style Structure 

The field style structure defines the overall behavior of the field. Information on the various flags can be 
found elsewhere. For information on focusStyle, capOutPut, popUpType, editType, xlateType, delayed 
and boxMemory, see above. 

For information on noSpace and veto, see msgFieldCreateTranslator. 



typedef struct FIELD_STYLE { 
U16 focusStyle: 2, 
capOutput : 3 , 
popUpType: 3, 
editType: 2, 
xlateType: 1, 
client Validate : 1, 
clientPreValidate : 
clientPostValidate : 
clientNotifylnvalid: 
clientNotif yReadOnly : 



U16 clientNotifyModified: 1, 
validatePending: 1, 
delayed: 1, 



uppercase: 1, 

noSpace: 1, 

privateDatal : 1, 

veto: 1, 

privateData2 : 1, 

boxMemory : 2 , 

dataMoveable : 1, 

dataCopyable : 1, 

reserved: 5; 
} FIELD STYLE, *P FIELD STYLE; 



// How field does selection and target 

// Upper case writer cap rules for xlate 

// Insertion pad style for fipReplaceAll 

// Type of editing in field 

// 0=xlate object, l=xtemplate 

// client performs validation 

1, // Notify client before validation 

1, // Notify client after successful valid 

1, // Notify client when invalid 

1; // Notify client when attempt to modify 

// readonly field 

// Notify client when field modified 

// Field not valid since last modification 

// Delayed translation field. Capture 

// strokes till msgFieldTranslateDelayed 

// Field and IP forced to upper case 

// Turn on no space in fid created xlate 

// Internal use only 

// Turn on veto in fid created xlate 

// Internal use only 

// Enable box memory in field and IP 



// Reserved for future use 



Popup Editing Types 

These defines are parameters in msgFieldCreatePopUp and msgFieldActivatePopUp. They specify what 
type of edit operation should be performed by this pop-up. Internally, an edit gesture (circle) in an 
fstlnline field or pen input into fstPopUp field will call these messages with fipReplaceAll. An insert 
caret in an fstlnline field will call with fiplnsert. 



#define fipReplaceAll 
tdefine fiplnsert 1 
#define fipReplaceRange 2 

Validation data structure 



// The IP displays/edits the field value 

// The IP inserts new text at the insertion pt 

// Unimplemented 



This data structure is used as a parameter to msgFieldValidateEdit, and msgFieldNotifylnvalid to 
capture all validation information. 

typedef struct { 

MESSAGE failureMessage; // Reason validation failed 

OBJECT field; // Field to validate 
} FIELD NOTIFY, *P FIELD NOTIFY; 
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Messages 



Arguments 



msgNew 

Creates and initializes a new instance of clsField. 

Takes P_FIELD_NEW, returns STATUS. Category: class message. 

typedef union FIELD_XLATE { 

OBJECT translator; 

P_XTM_ARGS pTemplate; 
} FIELD_XLATE, *P_FIELD_XLATE; 

typedef struct FIELD_NEW_ONLY { 

FIELD_STYLE style; // field style, see above 

FIELD_XLATE xlate; // xlate object or template 

U16 maxLen; // maximum field string length. means no limit 

U32 reserved; // reserved for future use, must be 

} FIELD NEW ONLY, *P FIELD NEW ONLY; 



Comments 



See Also 



#define fieldNewFields \ 

labelNewFields \ 

FIELD_NEW_ONLY field; 

typedef struct FIELD_NEW { 

fieldNewFields 
} FIELD_NEW, *P_FIELD_NEW; 

Will force the label.style to lsBoxTicks for fields of editType fstOverWrite. Overwrite fields must have 
label style of lsBoxTicks. Will force gWin.style.gestureEnable to TRUE. Extreme care should be taken 
if changing either of these. The xlate parameter in conjunction with style.xlateType specifies the type of 
translator the field uses. If xlateType is 0, and pNew->field.xlate.translator does not equal objNull, the 
translator will be used for all translations in the field and in the IP, and destroyed when the field is 
destroyed. If xlateType is 1, pNew->field.xlate.pTemplate is used to create, allocate, and compile a 
template. It will also be freed when the field is destroyed. A translator will be created and destroyed as 
needed via msgFieldCreateTranslator from this compiled template. msgFieldCreateTrans will also be 
used when xlateType is and pNew->field.xlate.translator is objNull. 

msgFieldSetXlate 



lessage 
trgumenf-s 



Comments 



msgNewDefaults 

Initializes the FIELD_NEW structure to default values. 

Takes P_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct FIELD_NEW { 

fieldNewFields 
} FIELD_NEW, *P_FIELD_NEW; 

Initializes the default values. Care should be taken when changing the default values of parent classes. 
Examples are win.flags.input, or gwin.style. 

Zeros out pNew->field and sets 

fid. field. style. dataMoveable = true; 

fid. field. style. dataCopyable = true; 

fid. field. style. focusStyle = fstlnputSelection; 

fid. field. style. capOutput = fstCapAsIs; 

fid. field. style. editType = fstlnline; 

fid . field . style . popUpType = f stCharBoxButtons ; 

fid. field. style. xlateType = fstXlateObject; 

fid. field. style. boxMemory = fstBoxMemoryFour; 

fid. field. maxLen = 64; 
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fid. border. style. edge = bsEdgeBottom; 

f Id. gwin. style. firstEnter = TRUE; 

f Id. gwin. style. askOtherWin = TRUE; 

fid. gwin. sty le . otherWinSaysYes = TRUE; 

fid. win. flags. input = inputTip | inputStroke | 
inputOutProx | inputlnk | inputEnter | 
inputHoldTimeout | inputLRContinue | 
inputAutoTerm | inputTimeout | inputHWTimeout ; 



Messoge 
Arguments 



msgFieldGetStyle 

Passes back the style value held by the field. 
Takes P_FIELD_STYLE, returns STATUS. 



♦define msgFieldGetStyle 

typedef struct FIELD_STYLE { 
U16 focus Style: 2, 
capOutput : 3 , 
popUpType: 3, 
edit Type : 2 , 
xlateType : 1 , 
client Validate: 1, 
clientPreValidate : 
clientPostValidate : 
clientNotify Invalid: 
clientNotif yReadOnly : 



U16 clientNotifyModified: 1, 

validatePending: 1, 

delayed: 1, 

uppercase: 1, 

noSpace : 1 , 

privateDatal : 1, 

veto: 1, 

privateData2 : 1, 

boxMemory: 2, 

dataMoveable : 1, 

dataCopyable : 1, 

reserved: 5; 
} FIELD STYLE, *P FIELD STYLE; 



MakeMsg(clsField, 1) 

// How field does selection and target 

// Upper case writer cap rules for xlate 

// Insertion pad style for fipReplaceAll 

// Type of editing in field 

// 0=xlate object, l=xtemplate 

// client performs validation 

// Notify client before validation 

// Notify client after successful valid 

// Notify client when invalid 

// Notify client when attempt to modify 

// readonly field 

// Notify client when field modified 

// Field not valid since last modification 

// Delayed translation field. Capture 

// strokes till msgFieldTranslateDelayed 

// Field and IP forced to upper case 

// Turn on no space in fid created xlate 

// Internal use only 

// Turn on veto in fid created xlate 

// Internal use only 

// Enable box memory in field and IP 



// Reserved for future use 



Message 
Arguments 



msgFieldSetStyle 

Sets the style of the field. 

Takes P_FIELD_STYLE, returns STATUS. 

♦define msgFieldSetStyle 

typedef struct FIELD_STYLE { 
U16 focusStyle: 2, 
capOutput: 3, 
popUpType: 3, 
edit Type: 2, 
xlateType: 1, 
clientValidate : 1, 
clientPreValidate : 1 , 
clientPostValidate : 1 , 
clientNotifylnvalid: 1, 
clientNotif yReadOnly: 1; 

U16 clientNotifyModified: 1, 



MakeMsg(clsField, 2) 



// How field does selection and target 

// Upper case writer cap rules for xlate 

// Insertion pad style for fipReplaceAll 

// Type of editing in field 

// 0=xlate object, l=xtemplate 

// client performs validation 

// Notify client before validation 

// Notify client after successful valid 

// Notify client when invalid 

// Notify client when attempt to modify 

// readonly field 

// Notify client when field modified 
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Comments 



validatePending : 


1, 


// 


delayed: 


1, 


// 
// 


uppercase : 


1, 


// 


noSpace : 


1, 


// 


privateDatal : 


1, 


// 


veto: 


1, 


// 


privateData2 : 


1, 


// 


boxMemory : 


2, 


// 


dataMoveable : 


1, 




dataCopyable : 


1, 




reserved: 


5; 


// 


} FIELD STYLE, *P FIELD 


STYLE; 





Field not valid since last modification 
Delayed translation field. Capture 
strokes till msgFieldTranslateDelayed 
Field and IP forced to upper case 
Turn on no space in fid created xlate 
Internal use only 
Turn on veto in fid created xlate 
Internal use only 
// Enable box memory in field and IP 



// Reserved for future use 



Return Volwe 



If the field is active, will return stsFailed. Setting or clearing the delayed flag will cause changes in 
wm.flags necessary to implement delayed fields. Setting the editType to fstOverWrite will set 
label.style.displayType to lsBoxTicks. Will cancel any current delayed translation taking place and 
remove the scribbles in the field. 

stsFailed The field is currently being edited. This is either through the pen, or a pop up IP. 



msgFieldGetXlate 

Passes back the translator information for the field. 

Takes P_UNKNOWN, returns STATUS. 

#define msgFieldGetXlate MakeMsg(clsField, 3) 

Comments If xlateType is 0, the parameter is assumed to be a P_OBJECT and the translator object id is returned. 

Otherwise the parameter is assumed to be a P_UNKNOWN and the COMPILED template is returned. 

See Also xtemplate.h.h 

msgFieldSetXIate 

Specifies the translator information for the field. 

Takes PJJNKNOWN, returns STATUS. 

♦define msgFieldSetXIate MakeMsg(clsField, 4) 

Comments If xlateType is 0, the argument is assumed to be P_OBJECT being a translator. The old translator is not 

destroyed. If xlateType is 1, the argument is assumed to be an uncompiled template (P_XTM_ARGS). The 
field code will compile the template and use it to create a translator. Any old compiled template will not 
be freed, and must be done so by a call to XTemplateFree() by the client. Calling on a delayed field will 
cancel the delayed field, destroying any scribbles captured by the field. 

Return Value stsFailed The field is currently being edited with the pen, or through an IP. 

See Also msgFieldCreateTranslator.h.h 



msgFieldGetMaxLen 

Passes back the maximum length allowed for input in the field. 

Takes PJJ16, returns STATUS. 

tdefine msgFieldGetMaxLen MakeMsg(clsField, 5) 
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Insertion Pad Messages 



msgFieldSetMaxLen 

Sets the Maximum length for input in the field. 

Takes P_U16, returns STATUS. 

tdefine msgFieldSetMaxLen MakeMsg (clsField, 6) 

Comments Sets the limit for the number of characters that are allowed in a field. If maxLen is 0, the maxLen is 

assumed to be a maxUl6. However, it is not recommended that fields of that size be created. If the value 
is less than the old value, the value displayed in the field will be truncated to the new value during the 
next edit. 



msgFieldSetCursorPosition 

Sets the cursor position of the keyboard insertion point in the field. * 

Takes P_U16, returns STATUS. 

#define msgFieldSetCursorPosition MakeMsg (clsField, 7) 

The cursor position will not be displayed unless the field has the input target. As a performance 
optimization, this message is not self-sent to set the cursor position. 

msgFieldGetCursorPosition 

Passes the current keyboard insertion cursor position in the field. 

Takes P_U16, returns STATUS. 

tdefine msgFieldGetCursorPosition MakeMsg (clsField, 8) 

If no cursor position has been set, is returned. As a performance optimization, this message is not 
self-sent to inquire cursor position. 



Insertion Pad Messages 



msgFieldActivatePopUp 

Called to cause an Insertion pad to be brought up for the field. 
Takes P_FIELD_ACTIVATE_POPUP, returns STATUS. 

#define msgFieldActivatePopUp MakeMsg (clsField, 18) 

typedef struct { 

U16 type; 

P_RECT32 pRect; 

U32 reserved; 

} FIELD_ACTIVATE_POPUP, * P_FIELD_ACTIVATE_POPUP; 

If msgFieldActivate has not been called (due to pen input into the field) it will be called. Will bring the 
up the IP at the passed in pRect location. If NULL, the IP will be centered over the field. The type of IP 
will be passed to msgFieldCreatePopUP. Will return stsFailed if the pop-up is not valid given the type 
and state of the field. For example, an fip Insert on a filled to maxLen field will return stsFailed. 

stsFailed A popup up could not be created given the state of the field. 
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msgFieldAcceptPopUp 

Causes the Insertion pad to be accepted. 

Takes void, returns STATUS. 

#define msgFieldAcceptPopUp MakeMsg(clsField, 19) 

Comments Called when the user collapses the insertion pad by hitting the OK button or accepts the IP. Can be 

called programatically as well. 

msgFieldCancelPopUp 

Cancels the edit in the pop-up insertion pad. 

Takes void, returns STATUS. 

#define msgFieldCancelPopUp MakeMsg(clsField, 20) 

Comments Causes the old value to be preserved unchanged. Called when the user hits the cancel button or cancels 

the IP. Can be called programatically as well. 

msgFieldCreatePopUp 

Creates and passes back the insertion pad when the pop up is invoked. 

Takes P_FIELD_CREATE_POPUP, returns STATUS. 

#define msgFieldCreatePopUp MakeMsg(clsField, 27) 

Arguments typedef struct { 

U16 type; 

OBJECT ip; 
U32 reserved; 
} FIELD_CREATE_POPUP, * P_FIELD_CREATE_POPUP; 

Comments Will create the insertion pad for use in the field. If type is fipReplaceAll, will look at style.popUpType 

to determine the type of IP to create. If type is fiplnsert, will look at the system preferences for writing 
style and create the appropriate type of Insertion pad. Will return stsFailed if the type is fiplnsert and 
the field data length is equal to maxLen. 

Return Value stsFailed The pop-up could not be created for the field. 



Delayed Field Messages 



msgFieldTranslateDelayed 

Translates a field with delayed captured strokes. 

Takes NULL, returns STATUS. 

tdefine msgFieldTranslateDelayed MakeMsg(clsField, 25) 

Comments Causes translation to occur for a field that has style. delayed and has captured strokes pending 

translation. Returns stsMessagelgnored if style.delayed is not set, or if there is no pending translation. 

Return Value stsMessagelgnore The field did not have a delayed scribble to translate. 
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Miscellaneous Messages 



msgFieldGetDelayScribble 

Returns the delayed scribble for delayed fields. 

Takes P_OBJECT, returns STATUS. 

♦define msgFieldGetDelayScribble MakeMsg(clsField, 26) 

Retym Value stsMessagelgnore The field did not have a delayed scribble to translate. Either not a delayed field or no 

scribbles in the field. 

msgFieldSetDelayScribble g 

Puts the field in delayed mode with the given scribble. ►- 

5 
Takes P.OBJECT, returns STATUS. ^ 

tdefine msgFieldSetDelayScribble MakeMsg(clsField, 30) "^ 

Return Volue stsFailed The field is currently being edited. This is either through the pen, an IP, or the field contains 

delayed strokes in delayed mode. Undefined behavior if called on a field with delayed scribbles. 



Miscellaneous Messages 



msgFieldClear 

Clears the value of the field. 
Takes NULL, returns STATUS. 

♦define msgFieldClear MakeMsg(clsField, 29) 

Comments Clears the delay scribble if one exists, otherwise clears the value of the field. 

msgFieldReadOnly 

Self called when an attempt is made to modify a read only field. 
Takes self, returns STATUS. 

♦define msgFieldReadOnly MakeMsg(clsField, 21) 

Comments Will send msgFieldReadOnly to control.client if clientNotifyReadOnly is set. it exists. 

msgFieldModified 

Self called when a a field is modified. 

Takes self, returns STATUS. 

♦define msgFieldModified MakeMsg(clsField, 22) 

Comments If the control.dirty bit is clear and the clientNotifyModified bit is set, will send msgFieldModified to 

control.client. Will set the control.dirty bit. It is the clients responsibility to clear this bit. Will also set 
the validatePending bit. This bit is cleared after successful validation. 

msgFieldKeyboardActivate 

Activates field for keyboard use. 

Takes void, returns STATUS. 

tdefine msgFieldKeyboardActivate MakeMsg(clsField, 23) 
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Comments Called by client whenever the field is activated for use with the keyboard. Primarily useful for item 

managers that are dealing with keyboard navigation between fields. 



msgFieldCreateTranslator 

Self called to create a translator. Passes back the translator. 

Takes P_OBJECT, returns STATUS. 

♦define msgFieldCreateTranslator MakeMsg(clsField, 15) 

Comments Used to create the translator based on the compiled template. Called when xlate.xlateType = 1 or when 

xlate.xlateType = and xlate. translator = NULL to create the translator. Will create the translator and 
respect the style.noSpace, style. veto, and style.capOutput settings (for all caps writers). This translator 
will be destroyed when msgFieldDeactivate is called. 



Validation Messages 



msgFieldValidate 

Peforms the validation protocall for a field. 

Takes void, returns STATUS. 

tdefine msgFieldValidate MakeMsg(clsField, 9) 

Comments Forces validation of a field. Called when the field loses the input target and validatePending is TRUE. 

Also called when translation is completed in a previouisly empty field. Returns non-error status for 
failed validation, or stsOK for a valid field. 

♦ calls msgFieldPreValidate on client if field.style.clientPreValidate 

♦ calls msgFieldValidateEdit on client or on self, depending on style.clientValidate 

♦ calls msgFieldNotifylnvalid if msgFieldValidateEdit returns > stsOK 

♦ calls msgFieldPostValidate on client if field.style.clientPostValidate and msgFieldValidateEdit 
returns stsOK 

♦ calls msgFieldFormat to format the field if msgFieldValidateEdit returns stsOK. 

♦ sets the validatePending bit to 
See Abo msgFieldValidateEdit 



msgFieldPreValidate 

Called on client if the field.style.clientPreValidate is set before validation. 

Takes self, returns STATUS. 

Idefine msgFieldPreValidate MakeMsg(clsField, 10) 

Comments Called on the control.client if clientPreValidate is set before validation. Allows clients to pre-process the 

value of a field before validation occurs. 

msgFieldValidateEdit 

Self call to perform validation on the field. 

Takes P_FIELD_NOTIFY, returns STATUS. 

♦define msgFieldValidateEdit MakeMsg(clsField, 11) 



Message 
Arguments 



Comments 
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typedef struct { 

MESSAGE failureMessage; // Reason validation failed 

OBJECT field; // Field to validate 

} FIELD_NOTIFY, *P_FIELD_NOTIFY; 

Called on self if clientValidate is false, or on the client if clientValidate is set. Returns stsOK when 
successful. Puts a failure message in the failureMessage field of P_FIELD_NOTIFY if not successful, and 
returns a non-error return code. Default returns stsOK. 



msgFieldNotifylnvalid 

Called to notify a field was invalid. 

Takes P_FIELD_NOTIFY, returns STATUS. 

#define msgFieldNotifylnvalid MakeMsg(clsField, 12) 

typedef struct { 

MESSAGE failureMessage; // Reason validation failed 

OBJECT field; // Field to validate 

} FIELD_NOTIFY, *P_FIELD_NOTIFY; 

Called on client if fld.field.style.notifylnvalid bit is set and the msgFieldValidateEdit returns a > stsOK 
return code. Allows clients to post a failure message for validation. 



Message 
Arguments 



Comments 



Comments 



Comments 



msgFieldPostValidate 

Self call to perform post-validation processing. 

Takes self, returns STATUS. 

♦define msgFieldPostValidate MakeMsg(clsField, 13) 

Called on client if field, style. clientPostValidate is set. Only called if msgFieldValidateEdit returns 
stsOK. Allows client to perform post validation processing. 

msgFieldFormat 

Self call to perform formatting. 

Takes void, returns STATUS. 

#define msgFieldFormat MakeMsg(clsField, 14) 

Self called after validation to perform any formatted the field requires to display itself correctly. Intended 
to be overridden by clients to support field formatting. Only called when msgFieldValidateEdit returns 
stsOK. 



Messages from other classes 



Comments 



msgFree 

Defined in object.h. 

Takes OBJJCEY, returns STATUS. 

Deactivates the field if necessary. Will free the translator if xlateType is and a translator was handed to 
the field. Will free the compiled template if xlateType is 1. Inherits ancestor behavior. 

object.h 
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msgSave 

Defined in object.h. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments Inherits ancestor behavior first and then stores in the resource file all information about the current state 

of the field, including the translator or template information or the delayed strokes the field contains. 
Fields will not save any information about a current editing operation (through a pop-up, keyboard, or 
pen) in effect. 

See Also object.h 

msgRestore 

Defined in object.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments Inherits ancestor information and restores all information about the field including translator 

information or the delayed strokes the field contains. 

See Also msgSave.h 

msglPDataAvailable 

Defined in insert.h. 

Takes OBJECT, returns STATUS. 

Comments Sent to the field from an insertion pad when there is data to retrieve from the pop-up pad. Depending 

on the operation that brought up the pad (an insert or edit gesture), will either insert the text from the 
pad at the current insertion point, or replace the value of the field with the IP value. Will destroy the 
pop-up pad created. 

See Also insert.h 

msglPCancelled 

Defined in insert.h. 

Takes OBJECT, returns STATUS. 

Comments Sent to the field when the insertion pad has been canceled. Will destroy the pad and any changes to the 

text in the pad are ignored. 

See Als© insert.h 

msgControlSetDirty 

Defined in control.h. 

Takes BOOLEAN, returns STATUS. 

Comments Inherits behavior from superclass. Will clear all character box memory stored for an overwrite field, 

allowing characters to be returned immediatly from the translator. 

See Also control.h 
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FONTLBOX.H 



This file contains the API for clsFontListBox. 

clsFontListBox inherits from clsStringListBox. 

Provides a listbox that is based on the list of currently installed fonts. 



#ifndef FONTLBOX_INCLUDED 
#define FONTLBOX_INCLUDED 

♦include <strlbox.h> 



tifndef STRLBOX_INCLUDED 
#endif 



JF Common #defines and typedefs 



typedef struct { 

U16 prune : 16; // FIM_PRUNE_CONTROL (see fontmgr.h) 

U16 spare : 16; // reserved 
} FONTLB_STYLE, *P_FONTLB_STYLE; 

Default FONTLB_STYLE: 

prune = fimNoPruning (see fontmgr.h) 



Arguments 



Comments 



msgNew 

Creates a font list box window. 

Takes P_FONTLB_NEW, returns STATUS. Category: class message. 

typedef struct { 

FONTLB_STYLE style; // overall style 

U32 spare; // reserved 

} FONTLB NEW ONLY, *P FONTLB NEW ONLY; 



\ 
\ 
font ListBox; 



See Also 



tdefine fontListBoxNewFields 

stringListBoxNewFields 

FONTLB_NEW_ONLY 
typedef struct { 

fontListBoxNewFields 
} FONTLB_NEW, *P_FONTLB_NEW; 

In response to msgNew, clsFontListBox will set pArgs->listBox.nEntries to zero and then call ancestor. 
It will then use msgFIMGetlnstalledldList to get the list of fonts currently installed in the system. For 
each font, clsFontListBox will add an entry using msgListBoxInsertEntry that has 'freeEntry' set to 
lbFreeDataDefault and 'data' set to the IM_HANDLE of the font. 

As a last step, the new listBox instance will be added as an observer of thelnstalledFonts. 

We recommend that clients set pArgs->listBox.style.filing = lbFileMin to avoid unexpected results after 
a font listBox has been restored. See the documentation for msgRestore below. 

msgFIMGetlnstalledldList obtain the short IDs of all installed fonts. 
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msgNewDefaults 

Initializes the FONTLB_NEW structure to default values. 

Takes P_FONTLB_NEW, returns STATUS. Category: class message. 

typedef struct { 

fontListBoxNewFields 
} FONTLB_NEW, *P_FONTLB_NEW; 

Zeroes out pArgs->fontListBox and sets: 

pArgs->stringListBox. style. role = slbRoleChoiceOl; 

msgFontListBoxGetStyle 

, Gets the style of a font listbox. 

Takes P_FONTLB_STYLE, returns STATUS. 

#define msgFontListBoxGetStyle MakeMsg(clsFontListBox, 1) 

essage typedef struct { 

rguments U16 prune : 16; // FIM_PRUNE_CONTROL (see fontmgr.h) 

U16 spare : 16; // reserved 
} FONTLB_STYLE, *P_FONTLB_STYLE; 

Messages from Other Classes 

msgFree 

Sent as the last of three msgs to destroy an object. 
Takes OBJJCEY, returns STATUS. 
smments The receiver will remove itself as an observer of thelnstalledFonts. 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

smments clsFontListBox responds by restoring its style values and resynchronizing its entries with respect to the 

list of installed fonts, as is done in msgNew. The restored instance is added as an observer of 
thelnstalledFonts. 

Note that this new information may differ from that which had been used the last time the listBox was 
saved, because the list of fonts installed in the system may have changed. Depending on how clsListBox 
filed its entry data, this may lead to odd behavior. The best approach is to use a LIST_BOX_STYLE.filing 
of IbFileMin so that clsListBox won't file any entry information or windows. Because after msgRestore 
the value obtained via msgStrListBoxGetValue may no longer match any entry, clients should use 
msgStrListBoxSetValue to change the value to a short ID from the new list of installed fonts. 

msgSave 

Causes an object to file itself in an object file. 
Takes P_OBJ_SAVE, returns STATUS. 
smmemts clsFontListBox responds by writing out its style values. 
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msgStrListBoxGetValue 

Passes back the value of a string listbox. 

Takes P_U32, returns STATUS. 

Comments clsFontListBox responds by calling ancestor, converting the resulting IM_HANDLE *pArgs into the 

FIM_SHORT_ID via msgFIMGetld, and setting *pArgs to this short id. 



msgStrListBoxSetValue 

Sets the value of a string listbox whose role is one of slbRoleChoice*. 

Takes U32, returns STATUS. 

Comments clsFontListBox responds by converting the incoming pArgs from a FIM_SHORT_ID into the 

IM_HANDLE for the font (msgFIMFindld) and then calling ancestor with this new pArgs. 

msgStrListBoxProvideString 

This message requests the client (or subclass) to provide a string. 

Takes P_STRLB_PROVIDE, returns STATUS. Category: self-sent/client responsibility. 

Comments clsFontListBox first checks whether pArgs->position is >= the number of fonts described by its cached 

information. If so, clsFontListBox returns stsFailed. 

Otherwise, clsFontListBox fills out pArgs->pString with the font name (obtained by using 
msglMGetName and the IM_HANDLE pArgs->data) and returns stsOK. 

Return Value stsFailed pArgs->position >= number of fonts 



8 



msglMInstalled 

A new item was installed. 

Takes P_IM_NOTIFY, returns STATUS. Category: observer notification. 

Comments clsFontListBox responds by resynchronizing its entries with respect to the list of installed fonts, as is 

done in msgNew. 



Comments 



msglMDeinstalled 

An item has been deinstalled. 

Takes P_IM_DEINSTALL_NOTIFY, returns STATUS. Category: observer notification. 

clsFontListBox responds by resynchronizing its entries with respect to the list of installed fonts, as is 
done in msgNew. 
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FRAME.H 



This file contains the API definition for clsFrame. 

clsFrame inherits from clsShadow. 

Frames support a single client window, surrounded by a host of optional "decorations" -- title bar, menu 

bar, close box, tab bar, command bar, etc. 



#ifndef FRAME_INCLUDED 
#define FRAME_INCLUDED 

tinclude <shadow.h> 



#ifndef SHADOW_INCLUDED 
#endif 



Common #defines and typedeffs 



typedef OBJECT FRAME; 
typedef struct FRAME_STYLE { 



U16 titleBar 
menuBar 
closeBox 
cmdBar 
tabBar 
pageNum 
zoomable 
clipBoard 
maskTitleLine 
maskMenuLine 
mask All 
maskCmdLine 
useAltVisuals 
sparel 

U16 spare2 



1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
3; 
16; 



// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 



show/don't show decoration 



true => zoom is allowed 

true => look like a clip board 

mask out the closeBox, titleBar, pageNum 

mask out the menuBar 

mask out title, menu and cmd lines 

mask out the cmdBar 

use alternate border visuals 

unused (reserved) 

unused (reserved) 



} FRAME_STYLE, *P_FRAME_STYLE; 
Default FRAME_STYLE: 



titleBar 

menuBar 

closeBox 

cmdBar 

tabBar 

pageNum 

zoomable 

clipBoard 

maskTitleLine 

maskMenuLine 

maskAll 

useAltVisuals 



= true 
= false 
= true 
= false 
- false 
= false 
= true 
= false 
= false 
= false 
= false 
= false 



for msgFrameZoomOK, msgFrameZoomed 



typedef struct FRAME_ZOOM { 



FRAME 
BOOLEAN 
WIN 
U32 
} FRAME ZOOM, 



frame; 
up; 

toWin; 
spare; 
*P FRAME ZOOM; 



// in: Frame to zoom. 

// in: True=zoom up, False=zoom down 

// out: Window to zoom to 

// unused (reserved) 
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Messages 



msgNew 

Creates a frame window. Passes back the resulting FRAME_METRICS in pArgs->frame. 
Takes P_FRAME_NEW, returns STATUS. Category: class message, 
typedef struct FRAME NEW ONLY { 



FRAME_STYLE 


style; 




WIN 


client Win; 


WIN 


titleBar; 


WIN 


menuBar; 


WIN 


closeBox; 


WIN 


cmdBar 




P_CHAR 


pTitle 




OBJECT 


client 




WIN 


tabBar 




WIN 


pageNum; 


U32 


sparel; 


U32 


spare2 





//in only for msgNew 

// page number 
// unused (reserved) 
// unused (reserved) 
} FRAME_NEW_ONLY, *P_FRAME_NEW_ONLY, 
FRAME_METRICS, *P_FRAME_METRICS; 

#define frameNewFields \ 
shadowNewFields \ 
FRAME_NEW_ONLY frame; 

typedef struct FRAME_NEW { 

frameNewFields 
} FRAME_NEW, *P_FRAME_NEW; 

clsFrame creates an instance of clsFrameBorder as the frame's border window to be the parent of all of 
the frame decorations (except the tabBar, which is a direct child of the frame). The border window is 
inserted as a child of the frame. 

If pArgs->frame.style.clipBoard is true, the frame is made opaque and many of the border.style values 
are changed to produce a clipboard style look. 

For each of the decoration visibility style bits (e.g. style. titleBar), the following is done: 

If the style value is true, and the corresponding decoration window (e.g.. titleBar) is not objNull, the 
window provided is inserted aschild of the frame border window. 

If the style value is true and no window is provided (e.g. titleBar objNull), a default instance of the 
decoration is created (e.g. msgNew clsTitleBar) and inserted as a child of the frame border window. 

If the style value is false, the provided decoration window is remembereduse when the style value is set 
to true. 

If style.menuBar is true, the border style of the menuBar is altered to have a bottom edge with thickness 
bsThicknessDouble and borderlnk bsInkGray66. 

If style.titleBar is true, the border style of the titleBar is altered to have a bottom edge with thickness 
bsThicknessDouble (if style.menuBar is false) or bsThicknessSingle (if style.menuBar is true) and 
borderlnk bsInkGray66. 

If style.closeBox is true, the border style of the closeBox is altered to match that of the titleBar. 

If style.cmdBar is true and style.clipBoard is false, the border style of the cmdBar is altered to have a top 
edge with thickness bsThicknessDouble and borderlnk bsInkGray33. 

If style.maskTitleLine is true, style.closeBox, style.titleBar and style.pageNum are all treated as though 
they are false. 
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If style.maskMenuLine is true, style.menuBar is treated as though it is false. 

If style.maskCmdLine is true, style.cmdBar is treated as though it is false. 

If style.maskAll is true, style.maskTitleLine, style.maskMenuLine, and style.maskCmdLine are all is 
treated as though they are true. 



Message 
Arguments 



Comments 



msgNewDefaults 

Initializes the FRAME_NEW structure to default values. 

Takes P_FRAME_NEW, returns STATUS. Category: class message. 

typedef struct FRAME_NEW { 

frameNewFields 
} FRAME_NEW, *P_FRAME_NEW; 

Zeroes out pArgs-> frame and sets 

pArgs->win. flags. style &= ~wsParentClip; 

pArgs->win. flags. style |= wsClipChildren | wsClipSiblings; 

pArgs->embeddedWin. style. selection = ewSelect; 
pArgs->frame. style. titleBar = true; 
pArgs->frame. style. closeBox = true; 
pArgs->frame. style. zoomable = true; 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments If the client of the frame is OSThisAPP(), this is remembered and reinstated in msgRestore. In any case, 

the client is not saved. 

Each of the frame decorations, including the clientWin, with WIN_METRICS.flags.style.wsSendFile on is 
filed, even if the corresponding visibility style bit (e.g. style. titleBar) is false. 



msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsFrame restores the instance from the file. If the client of the frame was OSThisAppO when filed, the 

client is set to OSThisAppO, otherwise objNull. 

Each of the filed decoration windows and the clientWin are restored. If the frame was zoomed when 
filed, the frame is unzoomed as in msgFrameZoom(false). 

For each of the following, if the corresponding child windows were not filed (i.e. wsSendFile was not 
on), and the visibility style is on, default instances will not be created and the visibility style will be set to 
false: menuBar, cmdBar, and tabBar. For example, if the frame was filed with style.menuBar true and 
the menuBar did not have wsSendFile on, the restored frame will have style.menuBar false, and the 
menuBar in FRAME_METRICS set to objNull. 
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msgFree 

Sent as the last of three msgs to destroy an object. 

Takes OBJ.KEY, returns STATUS. 

Comments All children of the frame border window are destroyed. Decoration windows with visibility style bits off 

are also destroyed. 

msgFrameGetMetrics 

Passes back the metrics. 

Takes P_FRAME_METRICS, returns STATUS. 

♦define msgFrameGetMetrics MakeMsg (clsFrame, 1) 

msgFrameSetMetrics 

Sets the metrics. 

Takes P_FRAME_METRICS, returns STATUS. 

#define msgFrameSetMetrics MakeMsg(clsFrame, 2) 

Comments clsFrame replaces existing decoration windows with those provided. For example, if pArgs->titleBar 

specifies a new titleBar, the existing titleBar is extracted from the window tree and the new titleBar 
inserted as a child of the frame border window. 

Note that the old decoration windows are not destroyed and are no longer referenced by the frame (the 
client is free to destroy them at this point). 

Frame style values are changed as in msgFrameSetStyle. 



msgFrameGetStyle 

Passes back the current style values. 

Takes P_FRAME_STYLE, returns STATUS. 

tdefine msgFrameGetStyle MakeMsg (clsFrame, 22) 



show/don't show decoration 



Messoge 


typedef 


struct FRAME STYLE { 




Arguments 


U16 


titleBar 


1, 


// 






menuBar 


1, 


// 






closeBox 


1, 


// 






cmdBar 


1, 


// 






tabBar 


1, 


// 






pageNum 


1, 


// 






zoomable 


1, 


// 






clipBoard 


1, 


// 






maskTitleLine 


1, 


// 






maskMenuLine 


1, 


// 






mask All 


1, 


// 






maskCmdLine 


1, 


// 






useAltVisuals 


1, 


// 






spare 1 


3; 


// 




U16 


spare2 


16; 


// 



true => zoom is allowed 

true => look like a clip board 

mask out the closeBox, titleBar, pageNum 

mask out the menuBar 

mask out title, menu and cmd lines 

mask out the cmdBar 

use alternate border visuals 

unused (reserved) 

unused (reserved) 



} FRAME STYLE, *P FRAME STYLE; 
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Message 
Arguments 



Comments 



msgFrameSetStyle 

Sets the style. 

Takes P_FRAME_STYLE, returns STATUS. 

#define msgFrameSetStyle MakeMsg(clsFrame, 23) 



typedef struct FRAME_STYLE { 



U16 titleBar 
menuBar 
closeBox 
cmdBar 
tabBar 
pageNum 
zoomable 
clipBoard 
maskTitleLine 
maskMenuLine 
maskAll 
maskCmdLine 
useAltVisuals 
spa re 1 

U16 spare2 



1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
3; 
16; 



// show/don't show decoration 

// 

// 

// 

// 

// 

// true => zoom is allowed 

// true => look like a clip board 

// mask out the closeBox, titleBar, pageNum 

// mask out the menuBar 

// mask out title, menu and cmd lines 

// mask out the cmdBar 

// use alternate border visuals 

// unused (reserved) 

// unused (reserved) 



} FRAME_STYLE, *P_FRAME_STYLE; 

The new decoration visibility style bits (e.g. style.titleBar) are treated as in msgNew. Setting a visibility 
bit to false results in extracting the corresponding decoration window (e.g. metrics.titleBar) from the 
frame border window. Note that the extracted decoration window is not destroyed; but remembered for 
later use when the visibility bit is set to true. 

If style.useAltVisuals is changed from false to true, the alternate frame border visuals are applied to the 
frame's border style. 

If style.useAltVisuals is changed from true to false, the normal frame border visuals are applied to the 
frame's border style. 

Note that changing style.clipBoard is not implemented. 



msgFrameGetClientWin 

Passes back metrics. clientWin. 
Takes P_WIN, returns STATUS. 

♦define msgFrameGetClientWin 



MakeMsg(clsFrame, 24) 



msgFrameSetCHentWin 

Sets metrics.clientWin. 
Takes WIN, returns STATUS. 

♦define msgFrameSetClientWin MakeMsg(clsFrame, 25) 
Comments The old clientWin, if any, is not destroyed and is no longer referenced by the frame. 



msgFrameGetMenuBar 

Passes back metrics.menuBar. 
Takes P_WIN, returns STATUS. 
♦define msgFrameGetMenuBar MakeMsg(clsFrame, 26) 
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msgFrameSetMenuBar 

Sets metrics.menuBar; also sets style.menuBar to true if pArgs is not objNull, else false. 
Takes WIN, returns STATUS. 

♦define msgFrameSetMenuBar MakeMsg(clsFrame, 27) 
Comments The menuBar is changed as in msgFrameSetMetrics. 



msgFrameDestroyMenuBar 

Sets style.menuBar to false and destroys the existing menu bar, if any. 

Takes VOID, returns STATUS. 

#define msgFrameDestroyMenuBar MakeMsg(clsFrame, 28) 



msgFrameSetTitle 

Sets the string in the metrics.titleBar. 
Takes P_CHAR, returns STATUS. 

tdefine msgFrameSetTitle MakeMsg(clsFrame, 3) 

Comments This results in msgLabelSetString to metrics.titleBar. 



msgFrameGetClient 

Passes back metrics.client. 
Takes P_OBJECT, returns STATUS. 

#define msgFrameGetClient MakeMsg(clsFrame, 4) 

msgFrameSetClient 

Sets metrics.client. 

Takes OBJECT, returns STATUS. 

#define msgFrameSetClient MakeMsg(clsFrame, 5) 

msgFrameGetAltVisuals 

Passes back the alternate border visuals. 

Takes P_BORDER_STYLE, returns STATUS. 

#define msgFrameGetAltVisuals MakeMsg(clsFrame, 29) 



msgFrameSetAltVisuals 

Sets the alternate border visuals. 
Takes P_BORDER_STYLE, returns STATUS. 

#define msgFrameSetAltVisuals MakeMsg(clsFrame, 30) 

Comments If style.useAltVisuals is true, the new alternate visuals are applied to the frame's border style. 
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msgFrameGetNormalVisuals 

Passes back the normal border visuals. 
Takes P_BORDER_STYLE, returns STATUS. 

#define msgFrameGetNormalVisuals MakeMsg(clsFrame, 31) 

Comments This is equivalent to msgBorderGetStyle if style. useAltVisuals is false. 

msgFrameSetNormalVisuals 

Sets the normal border visuals. 

O 

Takes P_BORDER_STYLE, returns STATUS. Q 

♦define msgFrameSetNormalVisuals MakeMsg(clsFrame, 32) 

Comments If style.useAltVisuals is false, the new normal visuals are applied to the frame's border style. 

msgFrameShowSelected 

Makes the frame look selected or not. 

Takes BOOLEAN, returns STATUS. 

♦define msgFrameShowSelected MakeMsg(clsFrame, 17) 

— ___ 

Enables or disables UI for moving. 

Takes BOOLEAN, returns STATUS. 

♦define msgFrameMoveEnable MakeMsg (clsFrame, 19) 

Comments clsFrame alters the border.style.drag of the metrics.titleBar to be bsDragHoldDown if pArgs is true, 

bsDragNone otherwise. 



msgFrameResizeEnable 

Enables or disables UI for resizing. 

Takes BOOLEAN, returns STATUS. 

♦define msgFrameResizeEnable MakeMsg (clsFrame, 20) 

Comments clsFrame alters the border, style, resize of self to be bsResizeCorner if pArgs is true, bsResizeNone 

otherwise. 

Passes back true if the frame is currently zoomed. 

Takes P_BOOLEAN, returns STATUS. 

♦define msgFramelsZoomed MakeMsg (clsFrame, 21) 

msgFrameDelete 

Asks the frame s client to delete the frame. 
Takes nothing, returns STATUS. 

♦define msgFrameDelete MakeMsg (clsFrame, 7) 

clsFrame forwards this message to the client with self as the pArgs. 



412 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



msgFrameClose 

Asks the frame's client to close the frame. 

Takes nothing, returns STATUS. 

fdefine msgFrameClose MakeMsg(clsFrame, 8) 

clsFrame forwards this message to the client with self as the pArgs. 



msgFrameFloat 

Asks the frame's client to float the frame. 

Takes VOID, returns STATUS. 

#define msgFrameFloat MakeMsg (clsFrame, 9) 

clsFrame forwards this message to the client with self as the pArgs. 



msgFrameZoom 

Zooms the frame up or down. 

Takes BOOLEAN, returns STATUS. 

#define msgFrameZoom MakeMsg (clsFrame, 6) 

Comments If style.zoomable is false, nothing is done and stsOK is returned. 

Otherwise, msgFrameZoomOK is sent to the client with the following FRAME_ZOOM parameters: 

frame = self; 
up = pArgs; 

toWin = objNull; 

If the client returns stsRequestDenied or does not set the FRAME_ZOOM.toWin, the client's status is 
returned. 

If the frame is already zoomed as pArgs requests, nothing is done and stsOK is returned. 

If pArgs is true and style.clipBoard is false, the frame is zoomed up as follows: 

♦ The frame is made opaque by turning off wsTransparent in WINJMETRICS.flags.style and turning 
off inputTransparent in WIN.METRICS .flags.input. 

♦ The border edges, shadow, margin and resize handles on the frame are all turned off. 

♦ The current frame window bounds and parent are remembered for restoration in unzoom. 

♦ The frame is extracted from its current parent and inserted as a child of the FRAME_ZOOM.toWin 
with a window bounds computed to zoom the inner rect of the frame into the 
FRAME_ZOOM.toWin. The inner rect is computed using msgBorderGetOuterOffsets on the frame. 

If pArgs is false and style.clipBoard is false, the frame is zoomed down as follows: 

♦ The frame is made transparent by turning on wsTransparent in WIN_METRICS.flags.style and 
turning on inputTransparent in WIN_METRICS.flags.input. 

♦ The border edges, shadow, margin and resize handles on the frame are all restored to their values 
before the zoom. 

♦ The frame is extracted from its current parent and inserted in its original parent with its original 
window bounds. 

After the frame is zoomed/unzoomed it is layed out via msgWinLayout to self. 



FRAME. H 413 

Messages 

clsFrame then sends the following notifications of the zoom/unzoom: 

♦ self-send msgFrameZoomed with the FRAME_ZOOM as pArgs. 

♦ msgFrameZoomed to its client with the FRAME_ZOOM as pArgs. 

♦ self-sends msgNotifyObservers with the following OBJ_NOTIFY_OBSERVERS parameters: 

msg = msgFrameZoomed; 

pArgs = address of FRAME_ZOOM used to zoom/unzoom; 

lenSend = sizeof (FRAME_ZOOM) ; 

t t 

msgFrameSelect o 

Selects the frame. - 

Takes VOID, returns STATUS. * 

♦define msgFrameSelect MakeMsg (clsFrame, 18) 

msgFrameSelectOK(self) is sent to the client. 

— ~^ 

Sent to the client when msgFrameZoom is received. 

Takes P_FRAME_ZOOM, returns STATUS. Category: client notification. 

♦define msgFrameZoomOK MakeMsg (clsFrame, 11) 

Aessoge typedef struct FRAME_ZOOM { 

irgum&nts FRAME frame; // in: Frame to zoom. 

BOOLEAN up; // in: True=zoom up, False=zoom down 

WIN toWin; // out: Window to zoom to 

U32 spare; // unused (reserved) 

} FRAME_ZOOM, *P_FRAME_ZOOM; 

msgFrameSelectOK 

Sent to the client when msgFrameSelect is received. 
Takes FRAME, returns STATUS. Category: client notification, 
♦define msgFrameSelectOK MakeMsg (clsFrame, 16) 

The client should alter the frame to look selected. 

Sent to client and observers after frame is zoomed. 

Takes P_FRAME_ZOOM, returns STATUS. Category: client & observer notification. 

♦define msgFrameZoomed MakeMsg (clsFrame, 12) 

Message typedef struct FRAME_ZOOM { 

Arguments FRAME frame; // in: Frame to zoom. 

BOOLEAN up; // in: True=zoom up, False=zoom down 

WIN toWin; // out: Window to zoom to 

U32 spare; // unused (reserved) 

} FRAME ZOOM, *P FRAME ZOOM; 
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msgFrameClosed 

Sent to client and observers after frame is closed. pArgs is the frame. 
Takes WIN, returns STATUS. Category: client & observer notification, 
tdefine msgFrameClosed MakeMsg(clsFrame, 13) 

Note: not implemented. 

msgFrameFloated 

Sent to client and observers after frame is floated. 

Takes VOID, returns STATUS. Category: client & observer notification. 

tdefine msgFrameFloated MakeMsg (clsFrame, 14) 

Comments Note: not implemented. 

Sent to client and observers after frame is brought to top. 

Takes VOID, returns STATUS. Category: client & observer notification. 

#define msgFrameTopped MakeMsg(clsFrame, 15) 

Comments Note: not implemented. 



Messages from Other Classes 



comments 



msgGWinForwardedGesture: 

Called to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

clsFrame maps certain gestures forwarded from the frame's titleBar into self-sent messages. Other 
gestures are forwarded to the frame's client. 

If the pArgs->uid is not metrics.titleBar or a direct child of metrics. titleBar, 

msgGWinForwardedGesture(pArgs) will be sent to the frame's client. clsFrame will return the client's 
return status from this message. 

The value of pArgs->msg is processed as follows: 

♦ If xgsFlickUp/Down and the system preference with tag tagPrDocZooming is prDocZoomingOn, 
msgFrameZoom(true/false) is self-sent. 

♦ If xgsCross, msgFrameDelete(pNull) is self-sent. 

♦ If xgsPlus, msgFrameSelect(pNull) is self-sent. 

♦ If xgs2Tap, msgFrameFloat(pNull) is self-sent. 

♦ If xgs3Tap, the frame's WINJMETWCS.flags.style.wsMaskWrapWidth/Height flags are cleared and 
msgWinLayout(WIN_METRICS.options=wsLayoutDefault) is self-sent. This results in a re-layout to 
the frame's desired size. 
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Messages from Other Classes 

If xgsTrplFlickUp and the DEBUG version of tk.dll is installed, msgWinDumpTree is self-sent 
with pArgs of self or theRootWindow if the '!' debug flag has value 1. Note that 
msgWinDumpTree requires the debug version ofwin.dll to be installed. This is usefull for 
debugging window layout problems. 

All other gestures result in msgGWinForwardedGesture(pArgs) to the frame's client. 
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msgTrackProvideMetrics 

Sent to a tracker client before tracker is created. 

Takes P_TRACK_METRICS, returns STATUS. Category: third-party notification. 

Comments If pArgs->minWH and pArgs->maxWH allow the width to change, pArgs->minWH.w is set to a small 

value to prevent the frame from being resized to zero. 

If pArgs->minWH and pArgs->maxWH allow the height to change, pArgs->minWH.h is set to prevent 
the frame from being resized smaller than the sum of the metrics.titleBar and metrics.menuBar heights. 

The value of pArgs->style.draw is altered to present the proper visual given the frame's style.tabBar and 
style.cmdBar. 

msgTrackProvideMetrics(pArgs) is sent to the frame's client. 



Comments 



msgWinSetFlags 

Sets the window flags. 

Takes P_WIN_METRICS, returns STATUS. 

clsFrame alters the metric.clientWin's window flags to match the wsShrinkWrapWidth/Height flags of 
the frame. 



msgCstmLayoutGetChildSpec 

Passes back the current spec for the specified child. 

Takes P_CSTM_LAYOUT_CHILD_SPEC, returns STATUS. Category: self-sent. 

»©mme«ts clsFrame responds by providing the custom layout constraints for metrics.tabBar, metrics. cmdBar, and 

the frame's border window. 

Note that the decoration windows and the metrics. clientWin are actually children of the frame's border 
window, which is an instance of clsFrameBorder. clsFrameBorder responds to 

msgCstLayoutGetChildSpec by providing the custom layout constraints for its children (e.g. titleBar at 
the top, menuBar below titleBar, etc.). 



Commenf-s 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes WIN.SEND, returns STATUS. 

If pArgs->msg is msgBorderProvideDeltaWin and the frame is zoomed, clsFrame returns stsOK. This 
prevents a zoomed frame from being resized. 
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GRABBOX.H 



This file contains the API definition for clsGrabBox. 

clsGrabBox inherits from clsObject. 

Provides popup grab handles; uses clsTrack internally. 

GrabBoxes are used primarily by clsBorder to display resize handles, although other uses are possible. 



#ifndef GRABBOX_INCLUDED 
♦define GRABBOX_INCLUDED 

♦include <clsmgr.h> 



#include <sysgraf.h> 



#ifndef CLSMGR_INCLUDED 

♦endif 

♦ifndef SYSGRAF_INCLUDED 

#endif 



Common #defines and typedefs 



typedef OBJECT 



GRAB BOX; 



Type styles 



#define gbTypeResize 

// 

// 

// 



// resize 

1 // unused (reserved) 

3 // unused (reserved) 



Locations styles 



♦define gbLocULCorner 
♦define gbLocURCorner 1 
♦define gbLocLRCorner 2 
♦define gbLocLLCorner 3 
♦define gbLocLeftEdge 4 
♦define gbLocRightEdge 5 
♦define gbLocBottomEdge 6 
♦define gbLocTopEdge 7 
♦define gbLocNone 8 
typedef struct GRAB_BOX_STYLE 

U16 type : 2, 

loc : 4, 

autoDestroy : 1, 

autoTakeDown : 1 , 

spare : 8 ; 
} GRAB_BOX_STYLE, *P_GRAB_BOX_ 

Default GRAB BOX.STYLE: 



// upper- left corner 
// upper- right corner 
// lower-right corner 
// lower-left corner 
// left edge 
// right edge 
// bottom edge 
// top edge 
//no edge 



{ 

// type of grab box 

// location of grab box 

// destroy self on take down 

// take down if pen is outside grab box 

// unused (reserved) 
STYLE; 



type 

loc 

autoDestroy 

autoTakeDown 



= gbTypeResize 
= gbLocULCorner 
= true 
= true 
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Argument 
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typedef struct GRAB_BOX_INFO { 

// 
// 
// 
// 
// 
// 
// 
// 
// 
// 
// 



WIN win; 
U16 thickness; 
U16 length; 
RECT32 outerMargin; 
BOOLEAN includeOuter; 
BOOLEAN penlsDown; 



XY32 

U16 

U16 

U32 

U32 



downXY; 
visuallnset; 
cornerRadius; 
spare 1; 
spare 2 ; 



window over which grab box will be drawn 

thickness of visible grab area, in twips 

length of visible grab area, in twips 

thickness of invisible grab area, in twips 

true to include invisible area 

true if pen is down (for msgGrabBoxShow) 

xy on pen down in win space (for msgGrabBoxShow) 

amount to inset length for visual, in twips 

radius for round corners (zero for square), in twips 

unused (reserved) 

unused (reserved) 



} GRAB BOX INFO, *P GRAB BOX INFO; 



msgNew 

Creates a grab box object. 

Takes P_GRAB_BOX_NEW, returns STATUS. Category: class message. 



typedef struct GRAB BOX NEW ONLY { 



GRAB BOX STYLE 


style; 




// 


overall 


style 


WIN 


client; 




// 


window 


to grab 


XY32 


xy; 




// 


unused 




WIN 


xyWin; 




// 


unused 




U8 


margin; 




// 


unused 




U32 


spare; 




// 


unused 


(reserved) 


} GRAB BOX NEW ONLY, *P 


GRAB BOX 


NEW ONLY, 




GRAB BOX METRICS, *P 


GRAB BOX 


METRICS; 




♦define grabBoxNewFields \ 










objectNewFields 


\ 










GRAB_BOX_NEW_ONLY 


grabBox 


; 






typedef struct { 












grabBoxNewFields 












} GRAB BOX NEW, *P GRAB 


BOX NEW; 











rgumenfs 



msgNewDefaults 

Initializes the GRAB_BOX_NEW structure to default values. 

Takes P_GRAB_BOX_NEW, returns STATUS. Category: class message. 

typedef struct { 

grabBoxNewFields 
} GRAB_BOX_NEW, *P_GRAB_BOX_NEW; 

Zeroes out pArgs->grabBox and sets 

pArgs->grabBox. style. autoDestroy = true; 
pArgs->grabBox. style. autoTakeDown = true; 



msgGrabBoxGetStyle 

Passes back current style values. 

Takes P_GRAB_BOX_STYLE, returns STATUS. 

♦define msgGrabBoxGetStyle MakeMsg(clsGrabBox, 1) 



typedef struct GRAB BOX STYLE { 



rgumetits 


U16 type 


2, 




loc 


4, 




autoDestroy 
autoTakeDown 


1, 
1, 




spare 


8; 



// type of grab box 

// location of grab box 

// destroy self on take down 

// take down if pen is outside grab box 

// unused (reserved) 



} GRAB BOX STYLE, *P GRAB BOX STYLE; 



Messoge 
Arguments 



GRABBOX.H 
Common #defines and typedefs 
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msgGrabBoxSetStyle 

Sets style values. 

Takes P_GRAB_BOX_STYLE, returns STATUS. 

#define msgGrabBoxSetStyle MakeMsg(clsGrabBox, 2) 

typedef struct GRAB_BOX_STYLE { 

// type of grab box 

// location of grab box 

// destroy self on take down 

// take down if pen is outside grab box 

// unused (reserved) 
} GRAB_BOX_STYLE, *P_GRAB_BOX_STYLE; 

Note that changing style.loc or style.type while the grab box is being shown is not supported. 



type 
loc 


2, 
4, 


autoDestroy 
autoTakeDown 


1, 
1, 


spare 


8; 



Comments 



msgGrabBoxGetMetrics 



Passes back current metrics. 

Takes P_GRAB_BOX_METRICS, returns STATUS. 

tdefine msgGrabBoxGetMetrics MakeMsg(clsGrabBox, 3) 



msgGrabBoxSetMetrics 



Comments 



Comments 



Sets metrics. 

Takes P_GRAB_BOX_METRICS, returns STATUS. 

tdefine msgGrabBoxSetMetrics MakeMsg (clsGrabBox, 4) 

Sets the style as in msgGrabBoxSetStyle. 



msgGrabBoxShow 

Puts up or takes down the grab box. 

Takes P_GRAB_BOX_INFO, returns STATUS. 

tdefine msgGrabBoxShow MakeMsg(clsGrabBox, 5) 



INFO { 

// window over which grab box will be drawn 
// thickness of visible grab area, in twips 
// length of visible grab area, in twips 
// thickness of invisible grab area, in twips 

; // true to include invisible area 

// true if pen is down (for msgGrabBoxShow) 

// xy on pen down in win space (for msgGrabBoxShow) 

// amount to inset length for visual, in twips 

; // radius for round corners (zero for square), in twips 
// unused (reserved) 
// unused (reserved) 
} GRAB_BOX_INFO, *P_GRAB_BOX_INFO; 

If pArgs is not pNull, clsGrabBox will grab input using InputSetGrab() and paint the grab box. If 
style.autoTakeDown is true, the grab box will be taken down when the pen leaves proximity or moves 
out of the grab box with the pen up. 

If pArgs is pNull, clsGrabBox will take down the grab box and self-send msgDestroy(pNull) if 
style. autoDestroy is true. 



Message 


typedef struct GRAB_BOX_ 


Arguments 


WIN win; 




U16 thickness; 




U16 length; 




RECT32 outerMargin; 




BOOLEAN includeOuter 




BOOLEAN penlsDown; 




XY32 downXY; 




U16 visuallnset; 




U16 cornerRadius 




U32 spare 1; 




U32 spare2; 
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The area on which the grab box was drawn will be damaged with msgWinDirtyRect when the grab box 
is taken down. 

The grab box is drawn in the rectangle computed by GrabBoxLocToRect(). 

IF Public Functions 

GrabBoxIntersect 

Determines where pRect is in win. Returns a grab box location, e.g. gbLocLRCorner. 

Returns U16. 

Function Prototype U16 EXPORTED GrabBoxIntersect ( 

P_GRAB_BOX_INFO plnfo, // info about grab box locations 
P_RECT32 pRect // Rect to intersect 

); 

Comments pRect->origin is commonly the coordinate of an event in plnfo->win s space, in device units. 

plnfo->thickness is the thickness (in twips) of the visible grab-sensitive area within plnfb->win. 

pInfo->outerMargin is the thickness (in twips) of the invisible grab-sensitive area within plnfo->win. 
pInfo->outerMargin.{origin.x, size.w} are margins for the left and right, respectively. 
pInfo->outerMargin.{origin.y, size.h} are margins for the bottom and top, respectively. 

plnfo->length is the length of each grab-sensitive area, in twips. 

If pInfo->includeOuter is true, the outer margin area is included in the rect for each grab box. 

This is used by clsBorder to place a grab box over the resize handles. 

GrabBoxLocToRect 

Computes the rectangle of the grabBox at the given location. 

Returns void. 

Function Prototype void EXPORTED GrabBoxLocToRect ( 

P_GRAB_BOX_INFO plnfo, // info about grab box locations 

U16 location, // e.g. gbLocBottom 

P_RECT32 pRect // Rect to locate 

); 

Comments plnfo is as described in GrabBoxIntersect(). 

The corresponding rect for location is returned in pRect, in device units. 

GrabBoxPaint 

Paints the grab box at the specified location. 

Returns STATUS. 

Function Prototype STATUS EXPORTED GrabBoxPaint ( 
P_GRAB_BOX_INFO plnfo, 
U16 loc, 

SYSDC dc, 

P_RECT32 pRect, 

BOOLEAN clearOuter, 

BOOLEAN on 

); 
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Comments plnfo is as described in GrabBoxIntersect(). 

If dc is not objNull, it will be used for the painting. 

If pRect is pNull, the corresponding rect for location will be used; otherwise pRect will be used. 

If clearOuter is true, all of pRect will be cleared before painting. 

If on is true, the grab box will be painted in black, otherwise gray66. 

This is used by clsBorder to paint the resize handles. 
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^Messages from other classes 



msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments clsGrabBox will respond to input events that trigger resizing. 

If pArgs->devCode is msgPenUp, msgPenOutProxUp, msgPenOutProxDown, or msgPenMoveUp 
and pArgs->xy is not in the rectangle of the grab box and style.autoTakeDown is true or msgPenDown 
has been received, the grab box is taken down as in msgGrabBoxShow(false). 

If pArgs->devCode is msgPenDown the following is done: 

msgTrackProvideMetrics is sent to metrics.client with the following_METRICS parameters: 

msgNewDefaults is sent to clsTrack to initialize a TRACK_METRICS 
struct and then: 

style. track = tsTrackResize; 

style. anchor = computed from self's style.loc; 

win = parent of metrics.client; 

client = self; 

clientData = window to be resized; 

initRect = bounds of metrics.client; 

minWH = small rectangle; 

maxWH = limited to stay within parent of metrics.client 

tag = tagBorderResize; 

If style.loc is gbLocLeftEdge or gbLocRightEdge, maxWH is altered toto horizontal resize. 

If style.loc is gbLocBottomEdge or gbLocTopEdge, maxWH is altered toto vertical resize. 

An instance of clsTrack is created and started via msgTrackStart. 

msgTrackDone 

Sent by a tracker when it's done. 

Takes P_TRACK_METRICS, returns STATUS. Category: client notification. 

Comments clsGrabBox responds by resizing metrics.client to pArgs->rect.size. 

If the width/height is changed, wsMaskWrapWidth/Height will be turned on in 
WIN_METPJCS.flags.style for metrics.client. 

The client window is resized by sending msgWinLayout with the following WIN_METRICS parameters: 

options = 0; 

bounds = pArgs->rect; 

If style.autoDestroy is true, msgDestroy(pNull) is self-posted. 
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ICHOICE.H 



This file contains the API for clsIconChoice. 

clsIconChoice inherits from clsChoice. 

IconChoices are exclusive choices with icon buttons and boxed-style previewing/on feedback. 

See the documentation for msgTkTableChildDefaults below. 

tifndef ICHOICE_INCLUDED 

tdefine ICHOICE_INCLUDED 

tifndef CHOICE_INCLUDED 

tinclude <choice.h> 

tendif 

tifndef ICON INCLUDED 



tinclude <icon.h> 



tendif 



Common #defines and fypedefs 

typedef OBJECT ICON_CHOICE; 

typedef struct ICON_CHOICE_STYLE { 

U16 spare : 16; // unused (reserved) 
} ICON_CHOICE STYLE, *P ICONCHOICE STYLE; 

msgNew 

Creates an iconChoice (and its nested icon windows). 

Takes P_ICON_CHOICE_NEW, returns STATUS. Category: class message. 



irgument 



ftessoge 



Comments 



typedef struct ICON_CHOICE_NEW_ONLY { 

ICON_CHOICE_STYLE style; // overall style 

ICONJJEW iconNew; // storage for default child new struct 

U32 spare; // unused (reserved) 

} ICON_CHOICE_NEW_ONLY, *P_ICON_CHOICE_NEW_ONLY; 

tdefine iconChoiceNewFields \ 
choiceNewFields \ 
ICON_CHOICE_NEW_ONLY iconChoice; 

typedef struct ICON_CHOICE_NEW { 

iconChoiceNewFields 
} ICON CHOICE NEW, *P ICON CHOICE NEW; 



msgNewDefaults 

Initializes the ICON_CHOICE_NEW structure to default values. 

Takes P_ICON_CHOICE_NEW, returns STATUS. Category: class message. 

typedef struct ICON_CHOICE_NEW { 

iconChoiceNewFields 
} ICON_CHOICE_NEW, *P_ICON_CHOICE_NEW; 

Sets up pArgs->tkTable.pButtonNew to create instances of clslcon with boxed-style previewing/on 
feedback by default as follows: 

pButtonNew->button. feedback = bsFeedbackBox; 
Zeroes out pNew.iconChoice. 
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p Messages from Other Classes 



msgTkTableChildDefaults 

Sets the defaults in P_ARGS for a common child. 

Takes PJJNKNOWN, returns STATUS. 

Comments Here is how an iconChoice processes this message: 

if <pArgs->object. class inherits from clsButton> { 
pArgs->butt on. style. feedback = bsFeedbackBox; 
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ICON.H 



This file contains the API definition for clslcon. 

clslcon inherits from clsMenuButton. 

Icons support drawing a picture as well as a label string. Several picture types are supported, including 
bitmap. 



♦ifndef ICON_INCLUDED 
♦define ICON_INCLUDED 

♦include <mbutton.h> 



♦ifndef MBUTTON_INCLUDED 
♦endif 



Common #defines and typedefs 



typedef OBJECT ICON; 



Picture Styles 



♦define isPictureBitmap 

♦define isPictureNone 1 

tdefine isPicturePixelmap 2 

// 3 



// picture is a bitmap 
//no picture 
// picture is a pixelmap 
// unused (reserved) 



Aspect Ratio Styles 



♦define isAspectWidthFromHeight 
♦define isAspectHeightFromWidth 
♦define isAspectAsIs 
// 



// compute width from height & sample size 

1 // compute height from width & sample size 

2 // use the width and height as-is 

3 // unused (reserved) 



Common Layout Units Picture Sizes 



♦define iconSizeNormal 
♦define iconSizeSmall 
typedef struct ICON_STYLE { 



U16 transparent 

picture 

freeBitmap 

open 

sizeUnits 

sampleBias 

aspect 

spare 1 
U16 spare2 



2, 
2, 
1, 
1, 
6, 
1, 
2, 
1; 
16; 



21 // standard size, both width and height 
10 // standard small size 

// make the background transparent 

// type of picture 

// true => msgDestroy to bitmap after provide 

// modify picture to look open 

// units for pictureSize, e.g. bsUnitsPoints 

// true => alter pictureSize for quality 

// aspect ration rule (e.g. isAspectWidthFromHeight) 

// unused (reserved) 

// unused (reserved) 



} ICON STYLE, *P ICON STYLE; 
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|F Messages 



msgNew 

Creates an icon window. 

Takes PJCONJSTEW, returns STATUS. Category: class message. 

Arguments typedef struct ICON_NEW_ONLY { 

ICON_STYLE style; // overall style 

SIZE16 pictureSize; // picture size, in device units 

U32 spare; // unused (reserved) 

} ICON_NEW_ONLY, *P_ICON_NEW_ONLY; 

tdefine iconNewFields \ 

menuButtonNewFields \ 

ICON_NEW_ONLY icon; 

typedef struct ICON_NEW { 

iconNewFields 
} ICON_NEW, *P_ICON_NEW; 

Comments If pArgs->icon.style.transparent is true, wsTransparent is turned on in pArgs->win.flags.style and 

bsInkExclusive will be or-ed into pArgs->border.style.backgroundInk. 

msgNewDefaults 

Initializes the ICON_NEW structure to default values. 

Takes P_ICON_NEW, returns STATUS. Category: class message. 

Message typedef struct ICON_NEW { 

Arguments iconNewFields 

} ICON_NEW, *P_ICON_NEW; 

Comments Zeroes out pArgs->icon and sets 

pArgs->gWin.style.gestureEnable = true; 

pArgs->border.style.backgroundInk = bsInkWhite I bsInkExclusive; 
pArgs->border. style. border Ink = bsInkWhite | bsInkExclusive; 

pArgs->border. style. previewAlter = bsAlterBorders; 
pArgs->border . style . selectedAlter = bsAlterBorders ; 
pArgs->border. style. edge = bsEdgeBottom; 
pArgs->border. style. shadow = bsShadowNone; 

pArgs->control. style. showDirty = true; 

pArgs->label . style . xAlignment = IsAlignCenter; 

pArgs->icon . style . freeBitmap = true; 
pArgs->icon. style. sampleBias = true; 
pArgs->icon. pictureSize. w = pArgs->icon. pictureSize. h = iconSizeNormal; 

Default ICON_STYLE: 

transparent = false 

picture = isPictureBitmap 

freeBitmap = true 

open = false 

sizeUnits = bsUnitsLayout 

sampleBias = true 

aspect = isAspectWidthFromHeight 
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Message 
Arguments 



Arguments 



Comments 



msglconGetStyle 

Passes back the current style values. 

Takes P_ICON_STYLE, returns STATUS. 

#define msglconGetStyle MakeMsg(clsIcon, 1) 



typedef struct ICON STYLE { 



U16 transparent 


2, 


// 


picture 


2, 


// 


freeBitmap 


1, 


// 


open 


1, 


// 


sizeUnits 


6, 


// 


sampleBias 


1, 


// 


aspect 


2, 


// 


spare 1 


1; 


// 


U16 spare2 


16; 


// 


ICON STYLE, *P ICON ST^ 


(LE; 





// make the background transparent 

// type of picture 

true => msgDestroy to bitmap after provide 

// modify picture to look open 

units for pictureSize, e.g. bsUnitsPoints 

true => alter pictureSize for quality 

aspect ration rule (e.g. isAspectWidthFromHeight) 

unused (reserved) 

unused (reserved) 



msglconSetStyle 

Sets the style values. 

Takes P_ICON_STYLE, returns STATUS. 

♦define msglconSetStyle MakeMsg(clsIcon, 2) 



typedef struct ICON STYLE { 



U16 transparent 


2, 


picture 


2, 


freeBitmap 


1, 


open 


1, 


sizeUnits 


6, 


sampleBias 


1, 


aspect 


2, 


sparel 


1; 


U16 spare2 


16; 



// make the background transparent 

// type of picture 

// true => msgDestroy to bitmap after provide 

// modify picture to look open 

// units for pictureSize, e.g. bsUnitsPoints 

// true => alter pictureSize for quality 

// aspect ration rule (e.g. isAspectWidthFromHeight) 

// unused (reserved) 

// unused (reserved) 



} ICON STYLE, *P ICON STYLE; 



If style.open changes, the rect of the picture is dirtied by self-sending msgWinDirtyRect. 
Note that changing style, transparent is not implemented. 



msglconGetPictureSize 

Passes back the picture size in style.sizeUnits. 

Takes P_SIZE16, returns STATUS. 

♦define msglconGetPictureSize MakeMsg(clsIcon, 3) 

msglconSetPictureSize 

Sets the picture size. 

Takes P_SIZE16, returns STATUS. 

♦define msglconSetPictureSize MakeMsg(clsIcon, 4) 

The new picture size should be in style.sizeUnits (e.g. bsUnitsLayout). clslcon will free the cached 
picture as in msglconFreeCache. 
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msglconGetActualPictureSize 

Computes and passes back the actual picture size in device units. 
Takes P_SIZE16, returns STATUS. 

tdefine msglconGetActualPictureSize MakeMsg(clsIcon, 10) 

This is equivalent using msglconGetPictureSize and converting to device units if style.sampleBias is 
false or style.picture is not isPictureBitmap. 

Otherwise, clslcon will compute and pass back the actual picture size used based on the sample size of 
the bitmap, the specified picture size and style.sizeUnits, style.aspect, and the device resolution of the 
icon's window device. 



Comments 



msglconFreeCache 

Frees the cached picture, if any. 

Takes pNull, returns STATUS. 

#define msglconFreeCache MakeMsg (clslcon, 8) 

If style.picture isPictureBitmap, is clslcon will send msglconProvideBitmap on the next 
msgWinRepaint. 

Note that clslcon does not self-send msgWinDirtyRect here. You should send msgWinDirty rect after 
msglconFreeCache if you want the icon to repaint before it is otherwise damaged. 

msglconGetRects 

Passes back the bounds for the picture in pArgs[0] and the label in pArgs[l]. 

Takes P_RECT32, returns STATUS. 

#define msglconGetRects MakeMsg (clslcon, 6) 

Comments Note that pArgs is an array of two RECT32 structs. Bounds are in device units, relative to the origin of 

the icon. 



Arguments 



Comments 



msglconProvideBitmap 

Sent to control client when icon needs the picture bitmap. 

Takes P_ICON_PROVIDE_BITMAP, returns STATUS. Category: self-sent and client notification. 

#define msglconProvideBitmap MakeMsg (clslcon, 7) 

typedef struct ICON_PROVIDE_BITMAP { 

WIN icon; // in: icon asking for the bitmap 

TAG tag; // in: window tag of icon 

OBJECT device; // in: device on which bitmap will be rendered 

SIZE16 pictureSize; // in: size of picture, device units 

OBJECT bitmap; // out: bitmap to render 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} ICON_PROVIDE_BITMAP, *P_ICON_PROVIDE_BITMAP; 

clslcon will self-send this message when it needs the picture bitmap. Subclasses can catch this message 
and provide the appropriate bitmap. 

If clslcon receives this message, the message will be forwarded on to the icon's control client. 
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After the subclass or client provides the bitmap, clslcon will copy the bitmap to a cached data structure 
for use when painting. If style.freeBitmap is true, clslcon will send msgDestroy to the bitmap after 
creating the cache. 

msglconCopyPixels 

Causes the icon to copy pixels from pArgs->srcWin to a pixelmap. 

Takes P_ICON_COPY_PIXELS, returns STATUS. 

♦define msglconCopyPixels MakeMsg (clslcon, 9) 

Arguments typedef Struct ICON_COPY_PIXELS { O 

WIN srcWin; // in: source window 

XY32 srcXY; // in: origin of area to copy, srcWin space 

U32 sparel; // unused (reserved) 

} ICON_COPY_PIXELS, *P_ICON_COPY_PIXELS; 

Comments If style.picture is not isPicturePixelmap or pArgs->srcWin is objNull, clslcon will return stsBadParam. 

The area copied has size of pictureSize and origin pArgs->srcXY in pArgs->srcWin space. The pixelmap 
will be used during msgWinRepaint. 

msglconSampleBias 

Computes the sample-biased size for a given picture size. 

Takes P_ICON_SAMPLE_BIAS, returns STATUS. Category: class message. 

tdefine msglconSampleBias MakeMsg (clslcon, 11) 

// default tolerance used buy clslcon 

// amount a picture size can be adjusted up or down for sample bias, 

//in layout units 

tdefine iconSampleTolerance 4 

Arguments typedef Struct ICON_SAMPLE_BIAS { 

// in: device window 

// in: snap-to tolerance, in layout units 
// in: sample size, in device units 
// in/out: picture size, in device units 
// in: units for size 
// in: aspect ratio style 
// unused (reserved) 
// unused (reserved) 
} ICON_SAMPLE_BIAS, *P_ICON_SAMPLE_BIAS; 

Comments clslcon will alter pArgs->size.w/h to be a multiple of pArgs->sampleSize.w/h. If the new 

pArgs->size.w/h is within pArgs->tolerance units from pArgs->sampleSize.w/h, the size is rounded up or 
down to the sample size. 

pArgs->sampleSize should be in device units. pArgs->size should be in the units described by 
pArgs->sizeUnits (e.g. bsUnitsLayout). pArgs->tolerance should be in layout units. pArgs->win is any 
window on the related device. 

If pArgs->aspect is isAspectWidthFromHeight, the width will be computed from the final height as 

size.w = size.h * (sampleSize.w / sampleSize.h); 

If pArgs->aspect is isAspectHeightFromWidth, the height will be computed from the final width as 

size.h - size.w * (sampleSize.h / sampleSize.w); 

This message can be sent to clslcon or any instance of clslcon. 



WIN 


win; 




U32 


tolerance; 




SIZE32 
SIZE32 


sampleSize; 
size; 




U16 


sizeUnits 


: 6, 


U32 


aspect 
sparel 
spare2 ; 


: 2, 
: 8; 



430 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



Here is the current "size bias" code. In this fragment sampleSize is the sample's width or height, size is 
the proposed picture with or height, tolerance is the "snap-to" tolerance. All values are in device units. 
The computed value is the sample-biased picture width or height. 

if (size > sampleSize) { 

S32 mult; 

S32 lowerValue, lowerDelta; 

S32 upperValue, upperDelta; 

mult = size / sampleSize; 
lowerValue = mult * sampleSize; 
lowerDelta = size - lowerValue; 
upperValue = (mult + 1) * sampleSize; 
upperDelta = upperValue - size; 
if (lowerDelta < upperDelta) { 

value = lowerValue; 

delta = lowerDelta; 
} else { 

value = upperValue; 

delta = upperDelta; 
} 
} else { 

delta = sampleSize - size; 
value = sampleSize; 
} 

if (delta <= tolerance) 
size = value; 

return size; 

|es from other classes 

msgWinSetTag 

Sets the window tag. 

Takes P_WIN_METRICS, returns STATUS. 

Comments If pArgs->tag is the same as the current window tag, nothing is done and stsOK is returned. 

If style.picture is isPictureBitmap, clslcon will self-send msglconFreeCache followed by 
msgWinDirtyRect to force a redraw of the icon picture. 
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ITABLE.H 



This file contains the API for clsIconChoice. 

clsIconTable inherits from clsToggleTable. 

IconTables are non-exclusive toggle tables with icon buttons and boxed-style previewing/on feedback. 

See the documentation for msgTkTableChildDefaults below. 



#ifndef ITABLE_INCLUDED 
#define ITABLE_INCLUDED 

♦include <ttable.h> 



♦include <icon.h> 



#ifndef TTABLE_INCLUDED 

#endif 

#ifndef ICON_INCLUDED 

#endif 



Common #defines and typedefs 



typedef OBJECT ICON_TABLE; 
typedef struct ICON_TABLE_STYLE { 

U16 spare : 16; // unused (reserved) 
} ICON TABLE STYLE, *P ICON TABLE STYLE; 



Arguments 



msgNew 

Creates an iconTable (and its nested icon windows). 

Takes P_ICON_TABLE_NEW, returns STATUS. Category: class message. 

typedef struct ICON_TABLE_NEW_ONLY { 

ICON_TABLE_STYLE style; // overall style 

ICON_NEW iconNew; // storage for default child new struct 

U32 spare; // unused (reserved) 

} ICON_TABLE_NEW_ONLY, *P_ICON_TABLE_NEW_ONLY; 

tdefine iconTableNewFields \ 
toggleTableNewFields \ 
ICON_TABLE_NEW_ONLY iconTable; 

typedef struct ICON_TABLE_NEW { 

iconTableNewFields 
} ICON TABLE NEW, *P ICON TABLE NEW; 



Message 
Arguments 



msgNewDefaults 

Initializes the ICON_TABLE_NEW structure to default values. 

Takes P_ICON_TABLE_NEW, returns STATUS. Category: class message. 

typedef struct ICON_TABLE_NEW { 

iconTableNewFields 
} ICON TABLE NEW, *P ICON TABLE NEW; 
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Comments Sets up pArgs->tkTable.pButtonNew to create instances of clslcon with boxed-style previewing/on 

feedback by default as follows: 

pButtonNew->button. style. feedback = bsFeedbackBox; 
pButtonNew->button. style. contact = bsCont act Toggle; 

Zeroes out pNew.iconTable. 

ssages from Other Classes 

msgTkTableChildDefaults 

Sets the defaults in P_ARGS for a common child. 

Takes P_UNKNOWN, returns STATUS. 

Comments Here is how an iconTable processes this message: 

if <pArgs->object .class inherits from clsButton> { 

pArgs->button. style. feedback = bsFeedbackBox; 
} 
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ITOGGLE.H 



This file contains the API definition for clsIconToggle. 

clsIconToggle inherits from clslcon. 

Icon toggles are toggle buttons with pictures for on and off states. These can be used to display an on/off 
mode switch. 



#ifndef ITOGGLE_INCLUDED 
#define ITOGGLE_INCLUDED 

#include <icon.h> 



tifndef ICON_INCLUDED 
#endif 



Common #defines and typedefs 

typedef OBJECT ICON_TOGGLE; 
typedef struct ICON_TOGGLE_STYLE { 

U16 spare : 16; // unused (reserved) 
} ICON_TOGGLE_STYLE, *P_ICON_TOGGLE_STYLE; 

Default off/on picture tags These are the resids for bitmaps in the system resource file The default 
bitmaps represent "ink mode" for off (a picture of a pencil) and "gesture mode" for on (a picture of a 
check mark) 



tdefine taglconToggleOff 
#define taglconToggleOn 



MakeTag (clsIconToggle, 1) 
MakeTag (clsIconToggle, 2) 



Messages 



msgNew 

Creates an icon toggle window. 

Takes P_ICON_TOGGLE_NEW, returns STATUS. Category: class message. 

Arguments typedef struct ICON_TOGGLE_NEW_ONLY { 

ICON_TOGGLE_STYLE style; // overall style 

TAG off Tag; // picture tag to use when off 

TAG onTag; // picture tag to use when on 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} ICON_TOGGLE_NEW_ONLY, *P_ICON_TOGGLE_NEW_ONLY; 

tdefine iconToggleNewFields \ 
iconNewFields \ 

ICON_TOGGLE_NEW_ONLY iconToggle; 

typedef struct ICON_TOGGLE_NEW { 

iconToggleNewFields 
} ICON_TOGGLE_NEW, *P_ICON_TOGGLE_NEW; 

Comments The fields you commonly set are: 

pArgs->iconToggle.offTag picture tag to use when button is off 
pArgs->iconToggle.onTag picture tag to use when button is on 
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msgNewDefaults 

Initializes the ICON_TOGGLE_NEW structure to default values. 

Takes P_ICON_TOGGLE_NEW, returns STATUS. Category: class message. 

typedef struct ICON_TOGGLE_NEW { 

i conToggleNewFie Ids 
} ICON_TOGGLE_NEW, *P_ICON_TOGGLE_NEW; 

Zeroes out pArgs->iconToggle and sets: 

pArgs->gWin. style. gestureEnable = false; 

pArgs->button. style. feedback = bsFeedbackNone; 
pArgs->button. style. contact = bsCont act Toggle; 

pArgs->icon.pictureSize.w = 8 
pArgs->icon.pictureSize.h = 8 

pArgs->iconToggle.offTag = taglconToggleOff ; 
pArgs->iconToggle.onTag = taglconToggleOn; 

Note that the default picture size is set to 8x8 layout units, which is the width and height of the system 
font. 

The default off and on tags represent bitmaps stored in the system resource file. These are the bitmaps 
for "ink mode" (off) and "gesture mode" (on). 



msglconToggleGetStyle 

Passes back the current style values. 

Takes P_ICON_TOGGLE_STYLE, returns STATUS. 

#define msglconToggleGetStyle MakeMsg(clsIconToggle, 1) 

typedef struct ICON_TOGGLE_STYLE { 

U16 spare : 16; // unused (reserved) 
} ICON TOGGLE STYLE, *P ICON TOGGLE STYLE; 



msglconToggJeSetStyle 

Sets the style values. 

Takes P_ICON_TOGGLE_STYLE, returns STATUS. 

#define msglconToggleSet Style MakeMsg(clsIconToggle, 2) 

typedef struct ICON_TOGGLE_STYLE { 

U16 spare : 16; // unused (reserved) 
} ICON TOGGLE STYLE, *P ICON TOGGLE STYLE; 



msglconToggleGetOnTag 

Passes back the onTag. 

Takes P_TAG, returns STATUS. 

#define msglconToggleGetOnTag MakeMsg(clsIconToggle, 3) 
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Messages from Other Classes 



msglconToggleGetOffTag 

Passes back the offTag. 

Takes P_TAG, returns STATUS. 

tdefine msglconToggleGetOffTag MakeMsg (clsIconToggle, 4) 



msglconToggleSetOnTag 

Sets the onTag. 

Takes TAG, returns STATUS. 

♦define msglconToggleSetOnTag MakeMsg (clsIconToggle, 5) 

Comments clsIconToggle will remember the onTag for use when the button is on. If the button is currently on, 

msglconFreeCache will be self-sent to free the current picture bitmap and use the new one. 

msglconToggleSetOfFTag 

Sets the offTag. 

Takes TAG, returns STATUS. 

tdefine msglconToggleSetOffTag MakeMsg (clsIconToggle, 6) 

Comments clsIconToggle will remember the offTag for use when the button is off. If the button is currently off, 

msglconFreeCache will be self-sent to free the current picture bitmap and use the new one. 



Messages from Other Classes 



msgButtonShowFeedback 

Shows the feedback for an on/off button if pArgs is true/false. 

Takes BOOLEAN, returns STATUS. Category: self-sent. 

Comments clsIconToggle will free the old bitmap via msglconFreeCache and cause the new one to be displayed by 

damaging the picture rectangle. The current feedback state will be remembered for use in 
msglconProvideBitmap, at which time the picture tag will be set to either the onTag (pArgs == true) or 
the offTag (pArgs == false). 

See Also msglconProvideBitmap 

msglconProvideBitmap 

Sent to control client when icon needs the picture bitmap. 

Takes P_ICON_PROVIDE_BITMAP, returns STATUS. Category: client notification. 

Comments clsIconToggle will alter pArgs->tag to be onTag if the current feedback state is on, or the offTag 

otherwise. This results in the client of the icon receiving this message and providing the on or off 
bitmap. 
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LABEL.H 



This file contains the API definition for clsLabel. 

clsLabel inherits from clsControl. 

Implements much of the appearance of many toolkit components inside the border: font, decoration, 
scale, orientation, etc. 



fy Debugging Flags 



The clsLabel debugging flag is '%'. Defined values are: 
flag4 (0x0010) msgSave/msgRestore info 
flag5 (0x0020) boxed string/paint dc 



#ifndef LABEL_INCLUDED 
♦define LABEL_INCLUDED 

tinclude <control.h> 
#include <sysgraf.h> 



tifndef CONTROL_INCLUDED 

tendif 

tifndef SYSGRAF_INCLUDED 

#endif 



Common #defines and fypedefs 



typedef OBJECT LABEL; 



Info style 



#define lsInfoString 
tdefine lsInfoWindow 
#define lsInfoStringld 
// 



// info is pString 

1 // info is WIN 

2 // info is a resource file string id 

3 // unused (reserved) 



Ppr X and Y alignment styles 



#define 
tdefine 
#define 
#define 
#define 
tdefine 



IsAlignLeft 

IsAlignCenter 

IsAlignRight 

IsAlignBottom 

IsAlignTop 

IsAlignCustom 



// left-justified 

1 // centered 

2 // right-justified 
IsAlignLeft // bottom- justified 
IsAlignRight // top- justified 

3 // send msgLabelAlign to self 



Pfr Decoration style 



tdefine lsDecorationNone 

tdefine lsDecorationBlank 1 

tdefine lsDecorationNonExclusiveOn 2 

tdefine lsDecorationExclusiveOff 3 

tdefine lsDecorationExclusiveOn 4 

tdefine lsDecorationPullRight 5 

tdefine lsDecorationNonExclusiveOff 6 // left blank and double bar 



//no decoration 

// blank space on left 

// left check and double bar 

// left blank and single bar 

// left check and single bar 

// pull-right arrow on right 
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♦define 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

tdefine 

II 

II 

II 



lsDecorationCheck 

lsDecorationCircle 

lsDecorationBox 

lsDecorationCheckedBox 

lsDecorationCheckedCircle 

lsDecorationHollowLeft 

lsDecorationHollowRight 

lsDecorationSolidLeft 

lsDecorationSolidRight 

lsDecorationPopup 

lsDecorationButtonOff 

lsDecorationButtonOn 

lsDecorationCustomLeft 

lsDecorationCustomRight 



7 // left checkmark 

8 //left empty circle 

9 //left empty box 

10 // left checked box 

11 // left checked circle 

12 // left hollow left delta 

13 // left hollow right delta 

14 // left solid left delta 

15 // left solid right delta 

16 // left solid right delta w/ space 

17 // left off button glyph 

18 // left on button glyph 

19 // left custom decoration 

20 // right custom decoration 

21 // unused (reserved) 
. . // unused (reserved) 
31 // unused (reserved) 



Font Type 



tdefine IsFontSystem 
tdefine IsFontCustom 
tdefine IsFontUser 
II 



// use the system font 

1 // use the specified font 

2 // use the system user font 

3 // unused (reserved) 



Common Scale Values, in layout units 



tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



IsScaleTiny 

IsScaleSmall 

IsScaleMedium 

IsScaleNormal 

IsScaleLarge 

IsScaleJumbo 

IsScaleHuge 



2 


// 


2/8 


x 


normal 


4 


// 


4/8 


X 


normal 


6 


// 


6/8 


X 


normal 


8 


// 


8/8 


X 


normal 


10 


// 


10/8 


X 


normal 


12 


// 


12/8 


X 


normal 


14 


// 


14/8 


X 


normal 



Rotation styles 



tdefine IsRotateNone 
tdefine lsRotate90 
tdefine lsRotatel80 
tdefine lsRotate270 



// degrees (horizontal, left to right) 

1 // 90 degrees (vertical, bottom to top) 

2 // 180 degrees (horizontal, right to left) 

3 1 1 210 degrees (vertical, top to bottom) 



Underline styles 



tdefine lsUnderlineNone 

tdefine lsUnderlineSingle 1 

tdefine lsUnderlineDouble 2 

// 3 



//no underline 
// single underline 
// double underline 
// unused (reserved) 



Box styles 



tdefine lsBoxNone 

tdefine lsBoxSquare 1 

tdefine lsBoxTicks 2 

tdefine lsBoxInvisible 3 



// no boxes 

// square box around each character 
// tick mark between characters 
// don' t draw the box lines 
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Pfr Number of rows/columns 



♦define lsNumAsNeeded 

♦define IsNumAbsolute 1 

// 2 

// 3 
typedef struct LABEL_STYLE { 

U16 infoType : 2, 

xAlignment : 2, 

yAlignment : 2, 

rotation : 2, 

underline : 2, 

strikeout : 1, 

decoration : 5; 

U16 numCols : 2, 

numRows : 2 , 

box : 2 , 

wordwrap : 1 , 

font Type : 2, 

scaleUnits : 6, 

stringSelected : 1; 

U16 spare2 : 16; 

} LABEL STYLE, *P LABEL STYLE; 



//as many rows /columns as needed 
// fixed number: rows/cols 
// unused (reserved) 
// unused (reserved) 

// type of pString field 

// x alignment style 

// y alignment style 

// text rotation 

// underline style 

// strikeout during msgDcDrawText 

// decoration style 

// style for number of columns 

// style for number of rows 

// boxing style 

// word wrap to next row 

system or custom font 

scale units style, e.g. bsUnitsLayout 
// whether content string shows sel'd visual 
// unused (reserved) 



// 
// 



Default LABEL_STYLE: 

infoType 

xAlignment 

yAlignment 

decoration 

scaleUnits 

rotation 

underline 

strikeout 

box 

numCols 

numRows 

wordwrap 

fontType 

scaleUnits 

stringSelected 



= lsInfoString 

= IsLeft 

= lsBottom 

= lsDecorationNone 

= bsUnitsLayout 

= IsRotateNone 

= lsUnderlineNone 

= false 

= lsBoxNone 

= lsNumAsNeeded 

= lsNumAsNeeded 

= false 

= IsFontSystem 

= bsUnitsLayout 

= false 



Messages 



Argument's 



msgNew 

Creates a label window. 

Takes P_LABEL_NEW, returns STATUS. Category: class message. 

typedef struct LABEL NEW ONLY { 



LABEL_STYLE 

P_CHAR 

SYSDC_FONT_SPEC 

P_CHAR 

U8 

U8 

U8 

U16 

U32 

U32 



style; // overall style 

pString; // string to display or child window 

font; // spec to open if style . fontType == IsFontCustom 

fontName; // font name from which to derive font. id 

scale; // scale in scaleUnits 

rows; // number of rows 

cols; // number of columns (or zero for infinite) 

customGlyph;// custom decoration glyph 

sparel; // unused (reserved) 

spare2; // unused (reserved) 



} LABEL NEW ONLY, *P LABEL NEW ONLY; 
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Idefine labelNewFields \ 
controlNewFields \ 
LABEL_NEW_ONLY label; 

typedef struct LABEL_NEW { 

labelNewFields 
} LABEL_NEW, *P_LABEL_NEW; 

Commesits The fields you commonly set are: 

pArgs->label.style appropriate style values 

pArgs->label.pString string or child window uid 

In response to msgNew, the label initializes all of its state. This is the only time pArgs->fontName 
would be used. 

Since clsLabel copies the bytes pointed to by pArgs->pString (when style.infoType is lsInfoString), the 
client may free the string after msgNew if the string was allocated. 

If style.infoType is IsInfoStringld, clsLabel self-sends msgLabelBindStringld to bind the resid to a 
string. 

msgNewDefaults 

Initializes the LABEL_NEW structure to default values. 

Takes P_LABEL_NEW, returns STATUS. Category: class message. 

Message typedef struct LABEL_NEW { 

Arguments labelNewFields 

} LABEL_NEW, *P_LABEL_NEW; 

Comments Zeroes out pArgs->label and sets: 

pArgs->win. flags. style |= wsShrinkWrapWidth | wsShrinkWrapHeight ; 

pArgs->border. style. leftMargin = bsMarginSmall; 
pArgs->border.style.rightMargin = bsMarginSmall; 
pArgs->border. style. bottomMargin = bsMarginSmall; 
pArgs->border.style.topMargin = bsMarginSmall; 

pArgs->label. style. scaleUnits = bsUnitsLayout; 
pArgs->label. scale = IsScaleNormal; 

Also sets pArgs->label.font to the default system font. 



msgLabelGetStyle 

Passes back the current style values. 

Takes P_LABEL_STYLE, returns STATUS. 

#define msgLabelGetStyle MakeMsg (clsLabel, 1) 

typedef struct LABEL_STYLE { 



Arguments 


U16 infoType 


2, 


// type of pString field 




xAlignment 


2, 


// x alignment style 




yAlignment 


2, 


// y alignment style 




rotation 


2, 


// text rotation 




underline 


2, 


// underline style 




strikeout 


1, 


// strikeout during msgDcDrawText 




decoration 


5; 


// decoration style 




U16 numCols 


2, 


// style for number of columns 




numRows 


2, 


// style for number of rows 




box 


2, 


// boxing style 
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wordwrap 


1, 


// 


font Type 


2, 


// 


scaleUnits 


6, 


// 


stringSelected 


1; 


// 


U16 spare2 


16; 


// 



} LABEL STYLE, *P LABEL STYLE; 



// word wrap to next row 
system or custom font 
scale units style, e.g. bsUnitsLayout 
whether content string shows sel'd visual 
unused (reserved) 



message 
Arguments 



Comments 



msgLabelSetStyle 

Sets the style fields. 

Takes P_LABEL_STYLE, returns STATUS. 

♦define msgLabelSetStyle MakeMsg(clsLabel, 2) 



typedef struct LABEL_STYLE { 



U16 infoType 
xAlignment 
yAlignment 
rotation 
underline 
strikeout 
decoration 

U16 numCols 
numRows 
box 

wordwrap 
font Type 
scaleUnits 
stringSelected 

U16 spare2 



2, 
2, 
2, 
2, 
2, 
1, 
5; 
2, 
2, 
2, 
1, 
2, 
6, 
1; 
16; 



// type of pString field 

// 

// 



x alignment style 
y alignment style 



// text rotation 

// underline style 

// strikeout during msgDcDrawText 

// decoration style 

// style for number of columns 

// style for number of rows 

// boxing style 

// word wrap to next row 

// system or custom font 

// scale units style, e.g. 



bsUnitsLayout 



// whether content string shows sel'd visual 
// unused (reserved) 



} LABEL_STYLE, *P_LABEL_STYLE; 

If the decoration style changes, the label uses msgWinDirtyRect to dirty the appropriate portion of 
itself. 

If the new style.box is not lsBoxNone, then the label self-sends msgLabelProvideBoxSize to obtain the 
width and height the boxes should be. If either of these differ from the old values, then the label 
self-sends msgWinSetLayoutDirty(true) . 

If the style.numCols or style. numRows change, or any of the other style values that might require 
relayout change, label self-sends msgWinSetLayoutDirty(true). 

It is the caller's responsibility to re-layout the label if the caller has changed any style that affects the 
layout of the label. 



msgLabelGetString 

Fills P_ARGS->pString with the current string. 

Takes P_CONTROL_STRING, returns STATUS. 

♦define msgLabelGetString MakeMsg(clsLabel, 3) 

Will fill the passed buffer up to len bytes worth of the string. The copied string is not null-terminated if 
the passed len wasn't large enough. 

If the passed len is zero, clsLabel sets len to the number of bytes the buffer would have to be in order to 
hold the entire label's string (including the terminating null). 
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msgLabelSetString 

Sets the label string. 

Takes P_CHAR, returns STATUS. 

fdefine msgLabelSetString MakeMsg(clsLabel, 4) 

stents Allocates storage and copies P_ARGS. Note that clsLabel allocates within the context of the current 

process. 

msgLabelGetUnicode 

Fills P_ARGS->pString with the current string. 

Takes P_CONTROL_STRING, returns STATUS. 

#define msgLabelGetUnicode MakeMsg (clsLabel, 21) 

•sent* Like msgLabelGetString, except that the client is requesting the string in Unicode format (where a 

character is represented in 16 bits). 

Will fill the passed buffer up to len characters worth of the string. The copied string is not 
null-terminated if the passed len wasn't large enough. 

If the passed len is zero, clsLabel sets len to the number of characters the buffer would have to be in 
order to hold the entire label's string (including the terminating null). Note that the number of bytes 
would be twice this number. 



msgLabelSetUnicode 

Sets the label string. 

Takes PJJ16 (P_CHAR after its 16-bit), returns STATUS. 

tdefine msgLabelSetUnicode MakeMsg (clsLabel, 22) 

Like msgLabelSetString, except that the client is specifying the string in Unicode format (where a 
character is represented in 16 bits). 

Allocates storage and copies P_ARGS. Note that clsLabel allocates within the context of the current 
process. 



msgLabelGetStringld 

Passes back the string resource id; zero if none. 

Takes P_RESID, returns STATUS. 

#define msgLabelGetStringld MakeMsg (clsLabel, 25) 

clsLabel returns stsFailed if style.infoType is not IsInfoStringld. 

msgLabelSetStringld 

Sets the string resource id. 

Takes RESID, returns STATUS. 

#define msgLabelSetStringld MakeMsg (clsLabel, 26) 

clsLabel immediately binds the specified string id to a string by self-sending msgLabelBindStringld. 

The string id is remembered and saved during msgSave. 
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msgLabelBindStringld 

Binds the string resource id to a string. 
Takes VOID, returns STATUS. 

#define msgLabelBindStringld MakeMsg(clsLabel, 27) 

Comments clsLabel returns stsFailed if style.infoType is not lsInfoStringld. 

clsLabel binds the current string id to a string by loading the string from theProcessResList. 



Comments 



msgLabelGetWin 



Passes back the child window. 

Takes P_WIN, returns STATUS. 

♦define msgLabelGetWin MakeMsg (clsLabel, 5) 

clsLabel returns stsFailed if style.infoType is not lsInfoWin. 



msgLabelSetWin 

Sets the child window. 

Takes WIN, returns STATUS. 

tdefine msgLabelSetWin MakeMsg (clsLabel, 6) 

Comments clsLabel returns stsFailed if style.infoType is not lsInfoWin. 

Since changing the window within the label sets the label's wsLayoutDirty bit, the caller should 
re-layout the label. 

msgLabelGetFontSpec 

Passes back the font spec. 
Takes P_SYSDC_FONT_SPEC, returns STATUS. 
#define msgLabelGetFontSpec MakeMsg (clsLabel, 8) 

Comments Note that this font spec is not used unless style.fontType is IsFontCustom. 



msgLabelSetFontSpec 

Sets the font spec. 

Takes P_SYSDC_FONT_SPEC, returns STATUS. 

tdefine msgLabelSetFontSpec MakeMsg (clsLabel, 9) 

Comments Note that this font spec is not used unless style.fontType is IsFontCustom. 

As with msgLabelSetStyle, it is the caller's responsibility to re-layout the label if the caller has changed 
any style that affects the layout of the label (such as certain fields in the font spec). Note that the label 
does not currently explicitly set its wsLayoutDirty bit in response to msgLabelSetFontSpec, but that 
this may change in the future. 
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msgLabelGetScale 

Passes back the font scale. 
Takes P_U8, returns STATUS. 

#define msgLabelGetScale MakeMsg(clsLabel, 10) 

Comments Note that the units of this scale are determined by style.scaleUnits. 



msgLabelSetScale 

Sets the font scale. 

Takes U8, returns STATUS. 

tdefine msgLabelSetScale MakeMsg(clsLabel, 11) 

Comments Note that the units of this scale are determined by style.scaleUnits. 

As with msgLabelSetStyle, it is the caller's responsibility to re-layout the label if the caller has changed 
any style that affects the layout of the label (such as the font scale). Note that the label does not currently 
explicitly set its wsLayoutDirty bit in response to msgLabelSetScale, but that this may change in the 



future. 



msgLabelGetRows 

Passes back the number of rows the label will size itself to. 
Takes P_U8, returns STATUS. 

#define msgLabelGetRows MakeMsg(clsLabel, 12) 

Comments Note that this is not used unless style.numRows is lsNumAbsolute. 



msgLabelSetRows 

Sets the number of rows the label will size itself to. 

Takes U8, returns STATUS. 

tdefine msgLabelSetRows MakeMsg(clsLabel, 13) 

Note that this is not used unless style.numRows is lsNumAbsolute. 

As with msgLabelSetStyle, it is the callers responsibility to re-layout the label if the caller has changed 
any style that affects the layout of the label (such as the number of rows). Note that the label does not 
currently explicitly set its wsLayoutDirty bit in response to msgLabelSetRows, but that this may change 



in the future. 



msgLabelGetCols 

Passes back the number of columns the label will size itself to. 
Takes P_U8, returns STATUS. 

♦define msgLabelGetCols MakeMsg(clsLabel, 14) 

Comments Note that this is not used unless style.numCols is lsNumAbsolute. 
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msgLabelSetCols 

Sets the number of columns the label will size itself to. 

Takes U8, returns STATUS. 

♦define msgLabelSetCols MakeMsg(clsLabel, 15) 

Comments Note that this is not used unless style. numCols is IsNumAbsolute. 

As with msgLabelSetStyle, it is the caller's responsibility to re-layout the label if the caller has changed 
any style that affects the layout of the label (such as the number of columnss). Note that the label does 
not currently explicitly set its wsLayoutDirty bit in response to msgLabelSetCols, but that this may 



O 



change in the future. 2 

msgLabelGetCustomGlyph 

Passes back the custom decoration glyph, zero if none. 

Takes PJJ16, returns STATUS. 

♦define msgLabelGetCustomGlyph MakeMsg(clsLabel, 23) 

Comments Note that this is not used unless style, decoration is lsDecorationCustomLeft or 

lsDecorationCustomRight. 

msgLabelSetCustomGlyph 

Sets the custom decoration glyph. 
Takes U16, returns STATUS. 

♦define msgLabelSetCustomGlyph MakeMsg(clsLabel, 24) 

Comments Note that this is not used unless style.decoration is lsDecorationCustomLeft or 

lsDecorationCustomRight. 

msgLabelGetBoxMetrics 

Passes back the current box metrics. 

Takes P_LABEL_BOX_METRICS, returns STATUS. 

♦define msgLabelGetBoxMetrics MakeMsg(clsLabel, 16) 

Arguments typedef struct LABEL_BOX_METRICS { 

// origin and size of boxed area 
// size of a single box 
// current ♦ of rows and columns 
// positive baseline offset from bottom of box 
// unused (reserved) 
// unused (reserved) 
// unused (reserved) 
} LABEL_BOX_METRICS, *P_LABEL_BOX_METRICS ; 

Comments The box metrics describe the arrangement and size of the box cells imaged by the label. These metrics 

are valid only if style.box is not lsBoxNone. 

All origins and sizes are in device units. 



RECT32 


boxRect; 


SIZE32 


singleBoxSize; 


U16 


rows, cols; 


U16 


baseline; 


U32 


spare 1; 


U32 


spare2; 


U32 


spare3; 
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msgLabelResolveXY 

Resolves a point to a character in the string. 

Takes P_LABEL_RESOLVE, returns STATUS. 

tdefine msgLabelResolveXY MakeMsg(clsLabel, 17) 

Arguments typedef struct LABEL_RESOLVE { 

XY32 xy; // in: point to resolve 

S32 index; // out: index of char at point 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} LABEL_RESOLVE, *P_LABEL_RESOLVE; 

Comments An index of -1 indicates point is not over any character. The xy should be relative to the label and 

expressed in device units. 

msgLabelAlign 

Self-sent if style.xAlignment or style.yAlignment is IsAlignCustom. 

Takes P_LABEL_ALIGN, returns STATUS. Category: self-sent. 

tdefine msgLabelAlign MakeMsg(clsLabel, 7) 

Arguments typedef struct LABEL_ALIGN { 

BOOLEAN alignX; // in: true if x alignment 

SIZE16 outerSize; // in: size of label outer rect (in twips) 

SIZE16 innerSize; // in: size of label inner rect (in twips) 

SIZE16 contentsSize; // in: size of label contents (in twips) 

C00RD16 offset; // out: computed x or y offset from origin 

U32 spare; // unused (reserved) 

} LABEL_ALIGN, *P_LABEL_ALIGN; 

Comment* Allows subclasses to compute alignment. The subclass should fill in pArgs->offset. 

msgLabelProvidelnsPt 

Self-sent message to obtain where to render insertion point. 

Takes P_S16, returns STATUS. Category: self-sent. 

#define msgLabelProvidelnsPt MakeMsg(clsLabel, 18) 

Receiver should return the zero-based index of the character at which the insertion point should be 
drawn. Non-boxed styles draw the insertion point before this character, boxed styles highlight the box 
around this character. 

If the returned index is -1, no insertion point is drawn. clsLabel responds by default with -1. 



msgLabelGetRects 

Computes the rectangle for each given character index. 
Takes P_LABEL_RECT, returns STATUS. 

#define msgLabelGetRects MakeMsg (clsLabel, 19) 

tdefine lgrlnsPtRect flagO 

typedef struct { 

SI 6 index; 

RECT32 rect; 

U16 flags; 

U16 spare; 
} LABEL RECT, *P LABEL RECT; 
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Comments pArgs points to an array of LABEL_RECTs. The receiver computes the rectangle for the character at the 

index for each index until it encounters one whose value is -1. The rects are relative to the label, and are 
expressed in device units. 

The indices should be sorted in increasing order. 



msgLabelProvideBoxSize 

Self-sent message to obtain the char box size. 
Takes P_SIZE16, returns STATUS. Category: self-sent. 



#define msgLabelProvideBoxSize MakeMsg(clsLabel, 20) O 

O 



merits Receiver should fill in *pArgs with the size of a character box, in points. This message is self-sent when a 

boxed label is processing the following messages: msglnit, msgRestore, msgLabelSetString, and 
msgLabelSetStyle . 

clsLabel responds by filling in *pArgs from the user preferences (using prCharBoxWidth and 
prCharBoxHeight from prefs.h). 

Messages from Other Classes 



msgWinLayoutSelf 

Tell a window to layout its children. 

Takes P_WIN_METRICS, returns STATUS. 

clsLabel responds by recomputing its layout parameters and by using msgWinDelta on its child window 
(if style.infoType is lsInfoWindow). 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments clsLabel responds by filing away all its state, including its string (if style.infoType is lsInfoString) or 

child window (if style.infoType is lsInfoWindow). 

Note that the child window must have wsSendFile set to be filed. If wsSendFile is not set, then msgSave 
does not save it, and a subsequent msgRestore sets the labels pString field to objNull. (wsSendFile is 
the default for clsBorder and its descendents). 



msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsLabel responds by restoring all of its state, including its string (if style.infoType is lsInfoString) or 

child window (if style.infoType is lsInfoWindow). 

If the child window was not filed during the msgSave, then after msgRestore the label's pString value is 
objNull. 



448 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



msgFree 

Sent as the last of three msgs to destroy an object. 

Takes OBJJCEY, returns STATUS. 

Comments clsLabel responds by freeing its string if style.infoType is lsInfoString and the string pointer is not null. 

clsLabel uses OSHeapBlockFree. 



Comments 



msgWinRepaint 

Tells a window to repaint itself. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

clsLabel responds by painting its decoration and string as appropriate. 



msgWinGetBaseline 

Gets the desired x,y alignment of a window. 

Takes P_WIN_METRICS, returns STATUS. 

Comments clsLabel responds by setting pArgs->bounds.origin. 

If the label is displaying a decoration, the x coordinate is set to the x offset of the rightmost decoration 
position (there's a small gap between this position and the start of the string/window). If the label has no 
decoration, then the x coordinate is set to the offset of the left side of the string/window. 

The y coordinate is set to a value derived from the label's innerRect origin and the baseline information 
from the label's font. This value is accurate in those cases where the label's bottom fits snugly around the 
string/window, but is incorrect in cases where this doesn't hold (e.g., a non-wsShrinkWrapHeight label 
that is taller than it needs to be). 

See Also msgBorderGetlnnerRect baseline coordinates are derived from this 

msgEmbeddedWinGetMark 

Get an embedded window mark. 

Takes P_EMBEDDED_WIN_MARK, returns STATUS. 

Comments clsLabel responds by copying into pArgs->label, then ensures that the buffer is terminated with a null 

character. 

If style.infoType is not lsInfoString, or the label's string is null or empty, then clsLabel does nothing. 



Comments 



msgBorderPaintForeground 

catagory: subclass window responsibility Receiver must paint the foreground, if any. 

Takes VOID, returns STATUS. 

clsLabel responds by using msgWinBeginPaint, painting its decoration and string as appropriate, and 
then sending msgWinEndPaint. 
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msgControlSetDirty 

Clears the dirty bit. 

Takes BOOLEAN, returns STATUS. 

Comments clsLabel responds by calling ancestor, then checking the CONTROL_STYLE.showDirty value. If this is 

false, clsLabel just returns. Otherwise, if the old CONTROL_STYLE.dirty value is different from the new 
value, then clsLabel uses msgWinDirtyRect to dirty its decoration (if it has one). 

See Also msgControlSetStyle sets the CONTROL_STYLE values 

msgControlSetMetrics sets the CONTROL_METRICS values O 



msgWinDirtyRect dirties a portion of a window 



msgControlSetStyle 

Sets the style values. 

Takes P_CONTROL_STYLE, returns STATUS. 

Comments clsLabel responds by calling ancestor, then checking the CONTROL_STYLE.showDirty value. If this is 

false, clsLabel just returns. Otherwise, if the old CONTROL_STYLE.dirty value is different from the new 
value, then clsLabel uses msgWinDirtyRect to dirty its decoration (if it has one). 

See Also msgControlSetDirty sets the CONTROL_STYLE.dirty bit 

msgControlSetMetrics sets the CONTROL_METRICS values 

msgWinDirtyRect dirties a portion of a window 



msgControlSetMetrics 

Sets the metrics. 

Takes P_CONTROL_METRICS, returns STATUS. 

Comments clsLabel responds by calling ancestor, then checking the CONTROL_STYLE.showDirty value. If this is 

false, clsLabel just returns. Otherwise, if the old CONTROL_STYLE. dirty value is different from the new 
value, then clsLabel uses msgWinDirtyRect to dirty its decoration (if it has one). 

See Also msgControlSetStyle sets the CONTROL_STYLE values 

msgControlSetDirty sets the CONTROL_STYLE. dirty bit 

msgWinDirtyRect dirties a portion of a window 
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LISTBOX.H 



This file contains the API for clsListBox. 
clsListBox inherits from clsScrollWin. 

Implements a scrolling list of windows (of arbitrary length). 

The windows that the listBox manages may be of any class, and they may be of different classes within a 
listBox. The windows may have different heights as well. The listBox will constrain their widths as per 
various style settings. 

A listBox is useful when the number of windows that could be displayed is unknown, variable, or large 
(say 30 or more). The listBox will, by default, destroy those windows that have scrolled out of view, thus 
keeping the number of windows in existence to a reasonable quantity. 

By using a listBox, you trade performance for generality. If the number of windows is likely to be small 
and not particularly variable, you may choose to put a tableLayout window in as the clientWin of a 
scrollWin instead. The visual effect would be the same as for a listBox, but each of the tableLayout's 
child windows would, by default, be around for the lifetime of the parent (and as more windows are put 
on the screen, the overall performance of the UI degrades). 

As with most UI Toolkit classes, you may use clsListBox as-is, or create your own subclass for special 
purposes. Since a common use of a listBox is to present a simple list of strings to the user, you may use 
clsStringListBox instead (see strlbox.h). That class presents a somewhat simpler API for this common 
usage. A subclass of clsStringListBox is clsFontListBox, which gets its strings from the list of currently 
installed fonts on the system. clsFontListBox proves useful in situations such as option sheets (see 
fontlbox.h). 



Debugging Flags 



The clsListBox debugging flag is 'K\ Defined values are: 
flagl 2 (0x1000) general 



tifndef LISTBOX_INCLUDED 
tdefine LISTBOX_INCLUDED 

#include <swin.h> 



tifndef SWIN_INCLUDED 
tendif 



Common #defines and typedefs 



typedef OBJECT LIST BOX; 



ListBox Filing Styles 



#define lbFileMin 
fdefine lbFileEntrylnfo 1 
♦define lbFileAll 2 

typedef struct { 

U16 filing : 2, 
spare : 14; 
} LIST BOX STYLE, *P LIST BOX STYLE; 



// file minimum data necessary 

// lbFileMin + entry info except windows 

// lbFileEntrylnfo + windows 
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Default style: 



filing = lbFileAll 

typedef struct { 

LIST_BOX_STYLE 

OBJECT 

U16 

U16 

U32 
} LIST BOX METRICS, 



style; 

client; // 

nEntries; // 

nEntriesToView; // 

spare ; 

*P LIST BOX METRICS; 



client to send list box messages to. 
total number of entries in list box. 
show this many entries at a time. 



Enuml6(LIST BOX DATA FREE MODE) { 



lbFreeDat aNot Vi s ible 
lbFreeDataWhenDestroyed : 
lbFreeDataByMessage 
lbFreeDat aDe fault 

}; 

Enuml6(LIST BOX ENTRY STATE) 



flagO, 
flagl, 
flag2, 
lbFreeDat aNotVi s ible 



I lbFreeDataWhenDestroyed 



lbSelected 
lbOpen 
lbBusy 
lbStateDefault 



flagO, 
flagl, 
flag2, 




}; 

typedef struct LIST BOX ENTRY { 



// Not selected, not open 



// 
// 



in/out : 

in: 

// in/out: 

// in/out: 

in/out : 

in/out : 



// 
// 



WIN listBox; 

U16 position; 

WIN win; 

U16 freeEntry; 

U16 state; 

P_UNKNOWN data; 

P_UNKNOWN arg; 

U32 spare; 
} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 
typedef struct LIST_BOX_POSITION_XY { 

XY32 place; //in 

U16 position; // in/out 

U32 spare; // unused (reserved) 
} LIST_BOX_POSITION_XY, *P_LIST_BOX_POSITION_XY; 

typedef struct LIST BOX ENTRY ENUM { 



requestor 

entry position 

entry window to display 

LI ST_BOX_DATA_FREE_MODE 

LIST_BOX_ENTRY_STATE 

client data 



// message specific argument 
// reserved 



U16 
U16 



U16 



P LIST BOX ENTRY 



U16 
U32 



max; 


// in 


count ; 


// in 




// 




// 




// out 


next ; 


// in 




// 




// 


pEntry; 


// in 




// out 




// 


flags ; 


// in 


spare; 


// unu 



size of pEntryf] array. 

# of entries to return in array. 
If count > max then memory may be 
allocated. 

# of valid entries in array. 
to start at beginning 

OR previous out value to pick up 

where we left off. 

Ptr to array of entries. 

If memory was allocated client 

should free the memory. 

state flags to filter on. 

(reserved) 



} LIST_BOX_ENTRY_ENUM, *P_LIST_BOX_ENTRY_ENUM; 

#def ine stsListBoxEmpty MakeStatus (clsListBox, 



1) 



msgNew 

Creates a list box (initially empty). 

Takes P_LIST_BOX_NEW, returns STATUS. Category: class message. 

typedef LIST_BOX_METRICS LIST_BOX_NEW_ONLY, *P_LIST_BOX_NEW_ONLY; 
♦define listBoxNewFields \ 

scrollWinNewFields \ 

LIST BOX NEW ONLY listBox; 



Arguments 



Comments 
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typedef struct { 

listBoxNewFields 
} LIST_BOX_NEW, *P_LIST_BOX_NEW; 

clsListBox sets the following values before calling its ancestor: 

pArgs->scrollWin. style. getDelta = false; 
pArgs->scrollWin. style. vertClient = swClientWin; 
pArgs->scrollWin. style. horizClient = swClientScrollWin; 
pArgs->scrollWin. style. getSize = true; 
pArgs->scrollWin . style . forward = swForwardGesture; 



Message 
irgumenfs 



Comment 



msgNewDefaults 

Initializes the LIST_BOX_NEW structure to default values. 

Takes P_LIST_BOX_NEW, returns STATUS. Category: class message. 

typedef struct { 

listBoxNewFields 
} LIST_BOX_NEW, *P_LIST_BOX_NEW; 

clsListBox sets the following values: 

pArgs->win. flags. style |= wsShrinkWrapHeight; 
pArgs->win . flags . style &= ~wsShrinkWrapWidth; 
pArgs->border. style. edge = bsEdgeAll; 
pArgs->scrollWin. style. expandChildWidth = true; 
pArgs->listBox. style. filing = lbFileAll; 
pArgs->listBox. client = objNull; 
pArgs->listBox.nEntries = 0; 
pArgs->listBox.nEntriesToView = 6; 
pArgs->listBox. spare = 0; 



msgListBoxGetMetrics 

Passes back the metrics for a listBox. 

Takes P_LIST_BOX_METRICS, returns STATUS. 

tdefine msgListBoxGetMetrics 



MakeMsg (clsListBox, 1) 



typedef struct { 

LIST_BOX_STYLE style; 

OBJECT client; // client to send list box messages to. 

U16 nEntries; // total number of entries in list box. 

U16 nEntriesToView; // show this many entries at a time. 

U32 spare; 

} LIST BOX METRICS, *P LIST BOX METRICS; 



ssag« 



msgListBoxSetMetrics 

Sets the metrics for a listBox. 

Takes P_LIST_BOX_METRICS, returns STATUS. 

tdefine msgListBoxSetMetrics MakeMsg (clsListBox, 2) 

typedef struct { 

LIST_BOX_STYLE style; 

OBJECT client; // client to send list box messages to. 

U16 nEntries; // total number of entries in list box. 

U16 nEntriesToView; // show this many entries at a time. 

U32 spare; 

} LIST BOX METRICS, *P LIST BOX METRICS; 
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Comments You should send msgWinLayout to the listBox if the value of nEntriesToView has changed. 

The listBox might ask for new entries after the SetMetrics call returns if the value of nEntries has 
changed. 

msgListBoxAppendEntry 

Appends an entry to the list box after the specified position. 

Takes P_LIST_BOX_ENTRY, returns STATUS. 

#define msgListBoxAppendEntry MakeMsg(clsListBox, 3) 

Messoge typedef struct LIST_BOX_ENTRY { 

Arguments 



its 



WIN 


listBox; 


// in/out: 


requestor 


U16 


position; 


// in: 


entry position 


WIN 


win; 


// in/out: 


entry window to display 


U16 


freeEntry; 


// in/out: 


LIST BOX DATA FREE MODE 


U16 


state; 


// in/out: 


LIST BOX ENTRY STATE 


P UNKNOWN 


data; 


// in/out: 


client data 


P UNKNOWN 


arg; 


// message 


specific argument 


U32 


spare; 


// reserved 


1 



} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 

Comments If win is objNull, the client will receive msgListBoxProvideEntry when the entry needs to be displayed. 

This is computationally expensive when the listBox has a parent. In other words, all work necessary to 
fix up the listBox is performed immediately. If you want to batch several calls, consider extracting the 
listBox first. 

«e Also msgListBoxInsertEntry similar, but inserts before 



msgListBoxInsertEntry 

Insert an entry to the list box before the specified position. 
Takes P_LIST_BOX_ENTRY, returns STATUS. 

tdefine msgListBoxInsertEntry MakeMsg(clsListBox, 4) 

mage typedef Struct LIST BOX ENTRY { 



WIN 


listBox; 


// in/out: 


requestor 


U16 


position- 


// in: 


entry position 


WIN 


win ; 


// in/out: 


entry window to display 


U16 


freeEntry; 


// in/out: 


LIST BOX DATA FREE MODE 


U16 


state; 


// in/out: 


LIST BOX ENTRY STATE 


P UNKNOWN 


data; 


// in/out: 


client data 


P UNKNOWN 


arg; 


// message 


specific argument 


U32 


spare ; 


// reserved 


I 



} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 

Comments If win is objNull, the client will receive msgListBoxProvideEntry when the entry needs to be displayed. 

This is computationally expensive when the listBox has a parent. In other words, all work necessary to 
fix up the listBox is performed immediately. If you want to batch several calls, consider extracting the 
listBox first. 

See Also msgListBoxAppendEntry similar, but appends after 



Comments 



Return \fmm 



.ommetifs 
leturn ¥olos 



Comments 
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msgListBoxRemoveEntiy 

Removes an entry from the list box. 

Takes U16, returns STATUS. 

tdefine msgListBoxRemoveEntry MakeMsg(clsListBox, 5) 

If the item was added with freeEntry != 0, then the item is freed automatically by the list box. 

This is computationally expensive when the listBox has a parent. In other words, all work necessary to 
fix up the listBox is performed immediately. If you want to batch several calls, consider extracting the 
listBox first. 

stsBadParam the specified position is >= number of entries 



msgListBoxGetEntry 

Gets an entry in a listBox by position. 
Takes P_LIST_BOX_ENTRY, returns STATUS. 
#define msgListBoxGetEntry 
typedef struct LIST_BOX_ENTRY { 



MakeMsg(clsListBox, 6) 



WIN 


listBox; 


// 


in/out: 


requestor 


U16 


position; 


// 


in: 


entry position 


WIN 


win; 


// 


in /out : 


entry window to display 


U16 


freeEntry; 


// 


in /out : 


LI ST_BOX_DATA_FREE_MODE 


U16 


state; 


// 


in/out : 


LI ST_BOX_ENTRY_STATE 


PJJNKNOWN 


data; 


// 


in/out : 


client data 


P UNKNOWN 


arg; 


// 


message 


specific argument 


U32 


spare; 


// 


reserved 


I 



} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 
Will pass back the last one if the passed position is maxU16. 
stsListBoxEmpty the list box has no entries 
stsNoMatch the list box has no entry at that position 

msgListBoxSetEntry 

Sets an entry's information. 

Takes P_LIST_BOX_ENTRY, returns STATUS. 

tdefine msgListBoxSetEntry 



MakeMsg(clsListBox, 7) 



typedef struct LIST_BOX_ENTRY { 



WIN 


listBox; 


// 


in/out: 


requestor 


U16 


position; 


// 


in: 


entry position 


WIN 


win; 


// 


in /out: 


entry window to display 


U16 


freeEntry; 


// 


in /out : 


LIST_BOX_DATA_FREE_MODE 


U16 


state; 


// 


in /out: 


LIST_BOX_ENTRY_STATE 


PJJNKNOWN 


data; 


// 


in /out : 


client data 


P UNKNOWN 


arg; 


// 


message 


specific argument 


U32 


spare ; 


// 


reserved 





} LIST BOX ENTRY, *P LIST BOX ENTRY; 



Typically this message is used to set an entry's data or flag values. 

This message prohibits the caller from changing whether the entry has a window (by specifying an 
objNull pArgs->win when the entry has a window or vice versa). Clients should use 
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Append/Insert/Remove for this purpose. msgListBoxSetEntry does support replacing a window with a 
different one. 

Replacing an entry window is computationally expensive when the listBox has a parent. 

Return Value stsListBoxEmpty the list box has no entries 

stsBadParam attempt to add or remove an entry 

msgListBoxFindEntry 

Finds the position of the given entry window/data. 

Takes P_LIST_BOX_ENTRY, returns STATUS. 

#define msgListBoxFindEntry MakeMsg(clsListBox, 8) 

Message typedef struct LIST_BOX_ENTRY { 

Arguments 



WIN 


listBox; 


// in/out: requestor 


U16 


position- 


// in: entry position 


WIN 


win ; 


// in/out: entry window to display 


U16 


freeEntry; 


// in/out: LIST_BOX_DATA_FREE_MODE 


U16 


state; 


// in/out: LIST_BOX_ENTRY_STATE 


PJJNKNOWN 


data; 


// in/out: client data 


P UNKNOWN 


arg; 


// message specific argument 


U32 


spare; 


// reserved 



} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 

Comments If pArgs->win is non-null, clsListBox searches for an entry whose window matches pArgs->win. If 

pArgs->win is null, then clsListBox searches for an entry whose data fields matches pArgs->data. 

ietorn Malum stsListBoxEmpty the list box has no entries 

stsNoMatch the list box had no matching entry 



msgListBoxEnum 

Enumerates the entries of a listBox according to the given flags. 

Takes P_LIST_BOX_ENTRY_ENUM, returns STATUS. 

#define msgListBoxEnum MakeMsg (clsListBox, 9) 

Message typedef struct LIST_BOX_ENTRY_ENUM { 

Arguments U16 max; // in = size of pEntry[] array. 

U16 count; //in = # of entries to return in array. 

// If count > max then memory may be 

// allocated. 

// out = # of valid entries in array. 

U16 next; //in = to start at beginning 

// OR previous out value to pick up 

// where we left off. 

P_LIST_BOX_ENTRY pEntry; // in = Ptr to array of entries. 

// out = If memory was allocated client 

// should free the memory. 

U16 flags; // in = state flags to filter on. 

U32 spare; // unused (reserved) 

} LIST BOX ENTRY ENUM, *P LIST BOX ENTRY ENUM; 



LISTBOX.H 
Common #defines and typedefs 



457 



Message 
Arguments 



Comments 



Arguments 



Comments 



Return Valye 



ftesscsge 
krqumerr 



Comments 



msgListBoxEntrylsVisible 



Passes back the visibility of an entry in a listBox. 
Takes PJLIST_BOX_ENTRY, returns STATUS. 

tdefine msgListBoxEntrylsVisible MakeMsg(clsListBox, 10) 

typedef struct LIST_BOX_ENTRY { 



WIN 


listBox; 


// in/out: 


requestor 


U16 


position; 


// in: 


entry position 


WIN 


win; 


// in/out: 


entry window to display 


U16 


freeEntry; 


// in/out: 


LIST BOX DATA FREE MODE 


U16 


state; 


// in/out: 


LIST BOX ENTRY STATE 


P UNKNOWN 


data; 


// in/out: 


client data 


P UNKNOWN 


arg; 


// message 


specific argument 


U32 


spare; 


// reserved 





} LIST BOX ENTRY, *P LIST BOX ENTRY; 



Sets the 'arg' field to zero if not visible, non-zero if visible. If the position is maxU16, then uses 
pArgs->win instead. 



msgListBoxXYToPosition 

Gets the position for a given listBox window coordinate. 

Takes P_LIST_BOX_POSITION_XY, returns STATUS. 

tdefine msgListBoxXYToPosition MakeMsg(clsListBox, 11) 

typedef struct LIST_BOX_POSITION_XY { 

XY32 place; //in 

U16 position; // in/out 

U32 spare; // unused (reserved) 

} LIST_BOX_POSITION_XY, *P_LIST_BOX_POSITION_XY; 

This message resolves positions only to currently visible entry windows. It does not attempt to 
interpolate arbitrary coordinates to positions. 

pArgs->place should be in the listBox's clientWin space. 

stsNoMatch the place did not intersect any currently visible entry windows 



msgListBoxMakeEntryVisible 

Makes the specified entry visible. 

Takes P_LIST_BOX_ENTRY, returns STATUS. 

♦define msgListBoxMakeEntryVisible 



MakeMsg(clsListBox, 12) 



typedef struct LIST_BOX_ENTRY 



WIN 


listBox; 


U16 


position; 


WIN 


win; 


U16 


freeEntry; 


U16 


state; 


P UNKNOWN 


data; 


P UNKNOWN 


arg; 


U32 


spare; 



// in/out: requestor 

// in: entry position 

// in/out: entry window to display 

// in/out: LIST_BOX_DATA_FREE_MODE 

// in/out: LIST_BOX_ENTRY_STATE 

// in/out: client data 

// message specific argument 

// reserved 



} LIST BOX ENTRY, *P LIST BOX ENTRY; 



If the specified position is maxU16, msgListBoxFindEntry is first used to find the given window. If the 
position is not visible, it will be scrolled so that its top is at the center of the view. Otherwise, the 
minimum amount is scrolled. No msgWinUpdate is required. 
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Self-Sent/Client Messages 

All of the messages in this section are first sent to the listBox itself. This is so that subclasses of 
clsListBox may intercept these messages and process them as desired. If these messages reach the 
clsListBox message handler, they will be forwarded on to the listBox client. 



msgListBoxProvideEntry 

Self-sent when a listBox needs a window for display. 

Takes P_LIST_BOX_ENTRY, returns STATUS. Category: self-sent/client responsibility, 
tdefine msgListBoxProvideEntry MakeMsg (clsListBox, 13) 

lessage typedef struct LIST BOX ENTRY { 



WIN 


listBox; 


// in/out: 


requestor 


U16 


position; 


// in: 


entry position 


WIN 


win; 


// in/out: 


entry window to display 


U16 


freeEntry; 


// in/out: 


L I ST_BOX_DATA_FREE_MODE 


U16 


state; 


// in/out: 


LIST_BOX_ENTRY_STATE 


PJJNKNOWN 


data; 


// in/out: 


client data 


P UNKNOWN 


arg; 


// message 


specific argument 


U32 


spare; 


// reserved 


L 



} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 

The client should pass back a window UID in the win field. The client should also set the freeEntry, 
state, and data fields as desired. Note that the state and data fields have no meaning to clsListBox; 
they're uninterpreted fields for the client to use for any purpose. 

A listBox will send this message even when the position it's asking for is >= the number of entries 
specified for the listBox. In this case, the client is free to return a non-zero status value, indicating to the 
listBox that no entry should be created for that position. Providing another entry window in this case 
allows the user to create new entries by merely scrolling past the end of the list. 

If the message reaches the standard listBox message procedure, the listBox will forward the message to 
the client. This scheme allows subclasses of clsListBox to handle the message in a different way. 

msgListBoxDestroyEntry 

Sent to the client for an entry that has lbFreeDataByMessage enabled. 
Takes P_LIST_BOX_ENTRY, returns STATUS. Category: self-sent/client responsibility, 
♦define msgListBoxDestroyEntry MakeMsg (clsListBox, 14) 

Message typedef struct LIST BOX ENTRY { 



WIN 


listBox; 


// in/out: 


requestor 


U16 


position; 


// in: 


entry position 


WIN 


win; 


// in/out: 


entry window to display 


U16 


freeEntry; 


// in/out: 


LI ST_BOX_DATA_FREE_MODE 


U16 


state; 


// in/out: 


LI ST_BOX_ENTRY_STATE 


PJJNKNOWN 


data; 


// in/out: 


client data 


P UNKNOWN 


arg; 


// message 


specific argument 


U32 


spare; 


// reserved 





} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 
Comments The client should destroy the entry win and free any storage pointed to by the entry's 'data' field. 
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msgListBoxEntryGesture 

Notifies the subclass / client that a gesture occurred over an entry. 

Takes P_LIST_BOX_ENTRY, returns STATUS. Category: self-sent/ client responsibility. 

tdefine msgListBoxEntryGesture MakeMsg (clsListBox, 15) 

Message typedef struct LIST_BOX_ENTRY { 

Arguments 



WIN 


listBox; 


// 


in/out: 


requestor 


U16 


position; 


// 


in: 


entry position 


WIN 


win; 


// 


in/ out: 


entry window to display 


U16 


freeEntry; 


// 


in /out : 


LIST BOX DATA FREE MODE 


U16 


state; 


// 


in /out : 


LIST BOX ENTRY STATE 


P UNKNOWN 


data; 


// 


in/out: 


client data 


P UNKNOWN 


arg; 


// 


message 


specific argument 


U32 


spare; 


// 


reserved 





} LIST_BOX_ENTRY, *P_LIST_BOX_ENTRY; 

Comments The 'arg' field contains a P_GWIN_GESTURE pointer. 

If the position is maxUl6, this means that the listbox currently has no entry windows. Any other value 
indicates the position of the entry window to which the gesture is directed. The listbox will use 
msgGWinTransformGesture to translate the coordinates in the GWIN_GESTURE to be relative to the 
entry window. 

The listbox returns (from its msgGWinGesture/msgGWinForwardedGesture handler) the status 
resulting from self-sending msgListBoxEntryGesture. This means that the client should return stsOK, 
stsRequestDenied, or stsRequestForward as appropriate. See gwin.h. 



Messages from Other Classes 



msgWinStartPage 

Advises window that it is on a printer, and printing is about to start. 
Takes pNull, returns STATUS. Category: advisory message. 
Comments clsListBox responds by ensuring that its clientWIn is appropriately populated with entry windows. 

msgWinGetBaseline 

Gets the desired x,y alignment of a window. 

Takes P_WIN_METRICS, returns STATUS. 

Comments clsListBox will set pArgs->bounds.origin.x to 0. If there is an entry window visible, 

pArgs->bounds.origin.y is set to: 

<top of scrollWin's inner window> - <row height> 

+ <y baseline of first visible entry window> 

If no entry window is visible, the y is set to 0. 
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MANAGER.H 



This file contains the API for clsManager. 

clsManager inherits from clsObject. 

Provides an abstract manager class and associated protocol. 

Managers are used to implement group behavior for collections of components. For example, each 
instance of clsChoice uses one to change the state of child buttons when the user is tapping on the 
choice's children. Also, the menu button holding onto a menu uid acts as a manager for that menu. 
Manager uids are held by instances of clsTkTable. 

tifndef MANAGER_INCLUDED 
#define MANAGER_INCLUDED 

#define managerNewFields \ 
objectNewFields 

A manager returns stsManagerContinue if it wishes msgWinSend propogation to continue. Any other 
return value causes propogation to stop and the return value to be passed back to the original 
msgWinSend sender. 
#define stsManagerContinue MakeMsg (clsManager, 1) 
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MBUTTON.H 



This file contains the API definition for clsMenuButton. 

clsMenuButton inherits from clsButton. 

Menu buttons support an optional pull-down or pull-right pop-up menu. 



#ifndef MBUTTON_INCLUDED 
tdefine MBUTTON_INCLUDED 

#include <button.h> 



tifndef BUTTON_INCLUDED 
tendif 



Common #defines and typedefs 



typedef OBJECT MENU BUTTON; 



Submenu Types 



#define mbMenuNone 





//no sub-menu defined 


#define mbMenuPullDown 


1 


// sub-menu is pull-down 


tdefine mbMenuPullRight 


2 


// sub-menu is pull-right 


tdefine mbMenuPopup 


3 


// sub -menu is popup 


tdefine mbMenuSibling 


4 


// sub-menu is a window sibling 


// 


5 


// unused (reserved) 


// 




// unused (reserved) 


// 


7 


// unused (reserved) 



Menu Actions 



tdefine mbActionlTap 
tdefine mbAction2Tap 1 



// menu up/down on xgslTap or msgPenUp 
// menu up/down on xgs2Tap 



typedef struct MENU BUTTON STYLE { 



U16 subMenuType 
getWidth 
getMenu 
enableMenu 
menuAction 
menuIsUp 
spare 



3, 
1, 
1, 
1, 
2, 
1, 
7; 



// sub-menu type 

// self-send msgMenuButtonProvideWidth 

// send msgMenuButtonProvideMenu to client 

// send msgControlEnable to menu 

// action to bring up/down menu 

// read-only: true => menu is up 

// unused (reserved) 



} MENU_BUTTON_STYLE, *P_MENU_BUTTON_STYLE; 
Default MENU_BUTTON_STYLE: 

subMenuType = mbMenuNone 
getWidth = false 

getMenu = false 

enableMenu = false 

menuAction = mbActionlTap 
menuIsUp = false 

typedef Struct MENU_BUTTON_PROVIDE_MENU { 

MENU_BUTTON menuButton; // In: requestor 

WIN menu; // In/Out: uid of menu 

U32 spare; // reserved (unused) 

} MENU BUTTON PROVIDE MENU, *P MENU BUTTON PROVIDE MENU; 
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Messages 



msgNew 

Creates a menu button window. 

Takes P_MENU_BUTTON_NEW, returns STATUS. Category: class message. 

typedef struct MENU_BUTTON_NEW_ONLY { 

MENU_BUTTON_STYLE style; // overall style 

WIN menu; // sub-menu or objNull 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} MENU_BUTTON_NEW_ONLY, *P_MENU_BUTTON_NEW_ONLY; 

#define menuButtonNewFields \ 

buttonNewFields \ 

MENU_BUTTON_NEW_ONLY menuButton; 

typedef struct MENU_BUTTON_NEW { 

menuButtonNewFields 
} MENU_BUTTON_NEW, *P_MENU_BUTTON_NEW; 

The fields you commonly set are: 

pArgs->menuButton.style.subMenuType kind of subMenu 

pArgs->menuButton.menu uid of menu window 

If pArgs->menuButton.style.subMenuType is mbMenuPullRight, sets pArgs->label.style.decoration to 
lsDecorationPullRight. 

If pArgs->menuButton.style.subMenuType is not mbMenuNone, sets pArgs->button.style.contact to 
bsContactToggle. 

If pArgs->menuButton.menu is not objNull, it self-sends msgWinSetPopup with WIN_METRICS 

parameters of child = menu; 



msgNewDefaults 

Initializes the MENU_BUTTON_NEW structure to default values. 

Takes P_MENU_BUTTON_NEW, returns STATUS. Category: class message. 

Message typedef struct MENU_BUTTON_NEW { 

Arguments menuButtonNewFields 

} MENU_BUTTON_NEW, *P_MENU_BUTTON_NEW; 

s Zeroes out pArgs-> menuButton and sets: 

pArgs->win. flags. style |= wsFileNoBounds; 

pArgs->border. style. edge = bsEdgeNone; 
pArgs->border. style. join = bsJoinSquare; 
pArgs->border. style. shadow = bsShadowNone; 

pArgs->gWin.style.gestureEnable = false; 

pArgs->control. style. showDirty = false; 

pArgs->label. style. xAlignment = IsAlignLeft; 
pArgs->label. style. yAlignment = IsAlignBottom; 
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msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

If the menu button has a menu, and the menu has wsSendFile on, msgSave be sent to the menu passing 
along pArgs. 



msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

clsMenuButton restores the instance from the file. If the menu buttona menu when filed, the menu is 
restored and the following is done:Sends msgTkTableSetManager, with pArgs of self to the menu. 
Self-sends msgWinSetPopup with WIN_METRICS parameters of child = menu; 



msgFree 

Sent as the last of three msgs to destroy an object. 

Takes OBJ_KEY, returns STATUS. 

If the menu button has a menu, msgDestroy is sent to the menu. 

msgMenuButtonGetStyle 

Passes back the current style values. 

Takes P_MENU_BUTTON_STYLE, returns STATUS. 

#define msgMenuButtonGetStyle MakeMsg (clsMenuButton, 1) 



typedef struct MENU_BUTTON_STYLE { 



U16 subMenuType 
getWidth 
getMenu 
enableMenu 


3, 
1, 
1, 
1, 


menuAction 


2, 


menuIsUp 


1, 


spare 


7; 



// sub -menu type 

// self-send msgMenuButtonProvideWidth 

// send msgMenuButtonProvideMenu to client 

// send msgControlEnable to menu 

// action to bring up/down menu 

// read-only: true => menu is up 

// unused (reserved) 



} MENU BUTTON STYLE, *P MENU BUTTON STYLE; 



msgMenuButtonSetStyle 



Sets the style values. 

Takes P_MENU_BUTTON_STYLE, returns STATUS. 

#define msgMenuButtonSetStyle MakeMsg (clsMenuButton, 2) 

typedef struct MENU_BUTTON_STYLE { 

// sub-menu type 

// self-send msgMenuButtonProvideWidth 

// send msgMenuButtonProvideMenu to client 

// send msgControlEnable to menu 

// action to bring up/down menu 

// read-only: true => menu is up 

// unused (reserved) 

} MENU_BUTTON_STYLE, *P_MENU_BUTTON_STYLE; 

Note that style.menuIsUp is read-only ~ pArgs->menuIsUp will be ignored. 



U16 subMenuType 
getWidth 
getMenu 
enableMenu 


3, 

1, 
1, 
1, 


menuAction 


2, 


menuIsUp 


1, 


spare 


7; 



466 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



If style.subMenuType changes the following is done: 

♦ if style.subMenuType is mbMenuPullRight, the label.style.decoration is set to to 
lsDecoratePullRight, otherwise it is set to IsDecorateNone. 

♦ if the menu button has a menu, button.style.contact is set to bsContactToggle, otherwise 
bsContactMomentary. 

♦ if the menu button has a menu, self-sends msgWinSetPopup with WIN_METRICS parameters of 
child = menu; 



msgMenuButtonGetMenu 

Passes back the menu, objNull if none. 

Takes P_MENU, returns STATUS. 

tdefine msgMenuButtonGetMenu MakeMsg(clsMenuButton, 3) 

Comments Note that this message does not result in msgMenuButtonProvideMenu to the menu button s client, 

even if style.getMenu is true. To retrieve the menu that will be shown, send 
msgMenuButtonProvideMenu to the menu button. 

See Also msgMenuButtonProvideMenu 

msgMenuButtonSetMenu 

Sets the menu. 

Takes MENU, returns STATUS. 

tdefine msgMenuButtonSetMenu MakeMsg(clsMenuButton, 4) 

Comments The submenu is only used if style.subMenuType is not mbMenuNone. Note that the old menu, if any, 

is not freed. If the new menu is not objNull, self-sends msgWinSetPopup with WIN_METRICS 
parameters of 

child = menu; 

msgMenuButtonProvideWidth 

Self-sent when style.getWidth is true. 

Takes P_S32, returns STATUS. Category: self-sent. 

#define msgMenuButtonProvideWidth MakeMsg(clsMenuButton, 7) 

Comments Subclasses should respond with the desired width of the menu button. clsMenuButton responds with 

selfs current window width. 

msgMenuButtonlnsertMenu 

Self-sent when style.menuAction is detected. 

Takes WIN, returns STATUS. Category: self-sent. 

#define msgMenuButtonlnsertMenu MakeMsg (clsMenuButton, 10) 

Comments Subclasses should respond by inserting pArgs into the window tree. If style.subMenuType is 

mbMenuSibling, clsMenuButton responds by inserting pArgs as a window sibling to self. Otherwise, 
msgMenuShow(true), is sent to pArgs. 
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msgMenuButtonExtractMenu 

Self-sent when style. menuAction is detected. 

Takes WIN, returns STATUS. Category: self-sent. 

tdefine msgMenuButtonExtractMenu MakeMsg(clsMenuButton, 11) 

merits Subclasses should respond by extracting pArgs from the window tree. clsMenuButton responds by 

sending msgMenuShow(false) to pArgs. If style.subMenuType is mbMenuSibling, clsMenuButton 
responds by sending msgWinExtract to pArgs. Otherwise, msgMenuShow(false), is sent to pArgs. 

2 

msgMenuButtonShowMenu Arguments o 

Enuml6(MENU_BUTT0N_SH0W_MENU) { ^ 

mbShowToggle =0, // toggle the state of the menu «sr 

mbShowExtract =1, // take down the menu Lbb 

mbShowInsert =2 // put up the menu 

}; 

msgMenuButtonShowMenu 

Puts up or takes down the menu. 

Takes MENU_BUTTON_SHOW_MENU, returns STATUS. 

tdefine msgMenuButtonShowMenu MakeMsg (clsMenuButton, 5) 



mes 



Enuml6(MENU_BUTTON_SHOW_MENU) { 
rguments mbShowToggle =0, // toggle the state of the menu 
mbShowExtract = 1, // take down the menu 
mbShowInsert =2 // put up the menu 
}; 



.CMTimenfs 



If the menu is currently up, and pArgs is mbShowToggle or mbShowExtract, does the following: 

♦ self-sends msgMenuButtonExtractMenu (menu). 

♦ if style.getMenu is true, sends msgMenuButtonMenuDone with the following 
MENU_BUTTON_PROVIDE_MENU parameters to the menu button's client: 

menuButton = self; 
menu = menu; 

If the menu is currently down, and pArgs is mbShowToggle or mbShowInsert, does the following: 

♦ if style.subMenuType is not mbMenuSibling and the menu has wsLayoutDirty set in its 
WIN_METRICS.flags.style, sends msgWinLayout with the following WIN_METRICS parameters to 
the menu: 



♦ 



options = wsLayoutResize; 
if style.getMenu is true, sends msgMenuButtonProvideMenu with the following 
MENU_BUTTON_PROVIDE_MENU parameters to the menu button's client (and then the resulting 
MENU_BUTTON_PROVIDE_MENU.menu will be used): 



menuButton = self; 
menu = menu; 



if style.enableMenu is true, the process of the selection owner is compared against the process of 
OSThisApp(). The menu is sent msgControlEnable with the following CONTROL_ENABLE 
parameters: 
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root = self; 

enable = true if processes match, false otherwise 

♦ msgMenuButtonPlaceMenu is self-sent with the following WIN_METRICS parameters: 

bounds. size = current menu size; 

bounds . origin = origin of self, in theRootWindow space; 

♦ msgWinDelta is sent to the menu to position it at the resulting origin. 

♦ msgTkTableSetManager(self) is sent to the menu. 

♦ self-sends msgMenuButtonlnsertMenu(menu). 

Note that if style.subMenuType is mbMenuSibling, msgWinLayout is not sent to self's parent. The 
caller must do this to insure the correct layout. 

msgMenuButtonPlaceMenu 

Self-sent whenever a menu button needs to position its associated menu. 

Takes P_WIN_METRICS, returns STATUS. Category: self-sent. 

tdefine msgMenuButtonPlaceMenu MakeMsg(clsMenuButton, 6) 

Comments If this message reaches clsMenuButton, that class will do some default positioning. In the message 

arguments: 

bounds, origin In origin of menu *button* wrt/ theRootWindow Out: origin of *menu* 
wrt/theRootWindow 

bounds.size In size of menu 

Since clsMenuButton uses msgMenuShow to display the menu, and that message always ensures that 
the menu lies within theRootWindow, there's no need in the method for msgMenuButtonPlaceMenu 
to check the bounds of the menu against theRootWindow. 

msgMenuButtonProvideMenu 

Sent to the client if style.getMenu is true. 

Takes P_MENU_BUTTON_PROVIDE_MENU, returns STATUS. Category: client responsibility. 

♦define msgMenuButtonProvideMenu MakeMsg (clsMenuButton, 8) 

Message typedef struct MENU_BUTTON_PROVIDE_MENU { 

Arguments MENU_BUTTON menuButton; // In: requestor 

WIN menu; // In/Out: uid of menu 

U32 spare; // reserved (unused) 

} MENU_BUTTON_PROVIDE_MENU, *P_MENU_BUTTON_PROVIDE_MENU; 

Comments clsMenuButton will send this message to the client of the menu button just before showing the menu. 

The MENU_BUTTON_PROVIDE_MENU parameters will be set as follows: 

menuButton = uid of menu button needing the menu 

menu = uid of last provided or set (via msgMenuButtonSetMenu) menu 

The client may modify the passed menu or supply a different menu uid. If the client makes changes to 
the menu that invalidate its layout or supplies a different uid, the client should lay out the menu before 
returning. If the client changes the uid of the menu, clsMenuButton will self-send 
msgMenuButtonSetMenu(pArgs->menu) (i.e. the menu button will remember the provided menu for 
future use). The client will be sent msgMenuButtonMenuDone when the menu button is finished with 
the menu. 
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Note that this message can also be sent to a menu button to retrieve the actual menu that would be 
shown by the menu button. If style.getMenu is true, clsMenuButton will send 
msgMenuButtonProvideMenu to the menu button's client. In this case, the caller must send 
msgMenuButtonMenuDone to the menu button when finished with the menu. 

See Also msgMenuButtonMenuDone 

msgMenuButtonMenuDone 

Sent to the client if style.getMenu is true. h. 

Takes P_MENU_BUTTON_PROVIDE_MENU, returns STATUS. Category: client responsibility. O 

tdefine msgMenuButtonMenuDone MsgNoError (MakeMsg (clsMenuButton, 9)) — 

Message typedef struct MENU_BUTTON_PROVIDE_MENU { « 

Arguments MENUJBUTTON menuButton; // In: requestor Laa 

WIN menu; // In/Out: uid of menu 

U32 spare; // reserved (unused) 

} MENU_BUTTON_PROVIDE_MENU, *P_MENU_BUTTON_PROVIDE_MENU; 

Comments clsMenuButton will send this message to the menu button's client when the menu button has taken 

down the menu and style.getMenu is true. Note that clsMenuButton does remember the uid of the 
menu even after sending this message. If the client destroys the menu, 
msgMenuButtonSetMenu(objNull) should be sent to the menu button. 

If clsMenuButton receives this message, and style.getMenu is true, this message will be forwarded to the 
menu button's client. 



Messages from Other Classes 



msgWinLayoutSelf 

Tell a window to layout its children. 

Takes P_WIN_METRICS, returns STATUS. 

Comments If the menu button has a menu, and style. getWidth is true and pArgs->options has wsLayoutResize set 

and the menu button has wsShrinkWrapWidth on, clsButton self-sends 
msgMenuButtonProvideWidth to compute pArgs->bounds.size.w. 

msgWinSend 

Sends a message up a window ancestry chain. 

Takes WIN_SEND, returns STATUS. 

Comments clsMenuButton acts as the manager for its menu, and looks for msgMenuDone to be sent via 

msgWinSend. 

If style.subMenuType is not mbMenuNone and pArgs->msg is msgMenuDone, and the menu is 
currently up, and pArgs->data[0] is not self, clsMenuButton will do the following: 

♦ take down the menu as in msgMenuButtonShowMenu. 

♦ self-send msgButtonSetNoNotify, false to turn off the menu button. 

♦ ObjectCallAncestorQ to all the msgWinSend to continue up the window tree. 
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If pArgs->data[0] is self, nothing is done and stsOK is returned without calling ancestor. This allows, for 
example, prevents a menu button with a pull-right menu from taking down the menu containing the 
menu button. 

___ ___ ^ 

Called to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

Comments If pArgs->msg is xgs2Tap and style.menuAction is mbAction2Tap and style.subMenuType is not 

mbMenuNone, the menu will be inserted/removed as in msgMenuButtonShow. 

clsMenuButton will notify its manager after any gesture. 

clsMenuButton self-sends msgButtonNotifyManager with the following BUTTON_NOTIFY parameters: 

msg = msgMenuDone; 

data = self; 
button = self; 

This is followed by ObjectCallAncestorQ, to allow the gesture to be processed normally. 



msgControlSetClient 

Sets the control metrics, client. 
Takes UID, returns STATUS. 
Comments clsMenuButton will send msgTkTableSetClient(pArgs) to the menu. 
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MCICON.H 



This file contains the API definition for clsMoveCopylcon. 

clsMoveCopylcon inherits from clslcon. 

Move-copy icons support the move/copy UI. Move-copy icon with drag style mcDragMove will appear 
with a single marquee. Move-copy icon with drag style mcDragCopy will appear with a double 
marquee. 



tifndef MCICON_INCLUDED 
tdefine MCICON_INCLUDED 

tinclude <icon.h> 



tifndef ICON_INCLUDED 
#endif 



Common #defines and typedefs 

typedef OBJECT MOVE_COPY_ICON; 

Drag Styles 

tdefine mcDragNone // disabled 

#define mcDragMove 1 // drag means move 

tdefine mcDragCopy 2 // drag means copy 

// 3 // unused (reserved) 

typedef struct MOVE COPY ICON STYLE { 



U16 move 


2, 


// private 


copy 


2, 


// private 


drag 


2, 


// drag behavior 


destroyOnSelChange 


1, 


// destroy self on msgSelChangedOwners 


spare 


9; 


// unused (reserved) 



} MOVE_COPY_ICON_STYLE, *P_MOVE_COPY_ICON_STYLE; 

tag for clsTrack instances created by clsMoveCopylcon 

#define tagMoveCopylconTrack MakeTag (clsMoveCopylcon, 1) 



Messages 



msgNew 

Creates a move-copy icon window. 

Takes P_MOVE_COPY_ICON_NEW, returns STATUS. Category: class message. 

Arguments typedef struct MOVE_COPY_ICON_NEW_ONLY { 

MOVE_COPY_ICON_STYLE style; // overall style 

U32 spare; // unused (reserved) 

} MOVE_COPY_ICON_NEW_ONLY, *P_MOVE_COPY_ICON_NEW_ONLY; 

#define moveCopylconNewFields \ 

iconNewFields \ 

MOVE_COPY_ICON_NEW_ONLY moveCopylcon ; 
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typedef struct MOVE_COPY_ICON_NEW { 

moveCopylconNewFields 
} MOVE_COPY_ICON_NEW, *P_MOVE_COPY_ICON_NEW; 

Comments If style.drag is not mcDragNone, sets the following: 

pArgs->win. flags. input |= inputMoveDown I inputMoveDelta; 
pArgs->win. flags. input &= -input LRContinue; 

pArgs->gWin.style.gestureEnable = false; 



pArgs->border. style. edge = bsEdgeAll; 

pArgs->border.style.leftMargin = bsMarginSmall; 

pArgs->border.style.rightMargin = bsMarginSmall; 

pArgs->border. style. bottomMargin = bsMarginSmall; 

pArgs->border.style.topMargin = bsMarginSmall; 

pArgs->border. style. border Ink - bsInkBlack; 

pArgs->border . style . lineStyle = 

(pArgs->moveCopyIcon. style. drag == mcDragMove) ? 
bsLineMarquee : bsLineDoubleMarquee; 

pArgs->border. style. selected = true- 

Note that if you set style.destroyOnSelChanged to true, you must add the move copy icon as an 
observer of theSelectionManager to have the move copy icon notified when the selection changes. 



Message 
Arguments 



Comments 



msgNewDefaults 

Initializes the MOVE_COPY_ICON_NEW structure to default values. 

Takes P_MOVE_COPY_ICON_NEW, returns STATUS. Category: class message. 

typedef struct MOVE_COPY_ICON_NEW { 

mo veCopy I conNewF i e Ids 
} MOVE_COPY_ICON_NEW, *P_MOVE_COPY_ICON_NEW; 

Zeroes out pArgs->moveCopyIcon and sets 

pArgs->moveCopyIcon . style . move = mcMoveCopyEnable ; 
pArgs->moveCopyIcon. style. copy = mcMoveCopyEnable; 

Default MOVE_COPY_ICON_STYLE: 

drag = mcDragNone 

destroyOnSelChange = false 



Messoge 
Argument 



msgMoveCopylconGetStyle 

Passes back the current style values. 

Takes P_MOVE_COPY_ICON_STYLE, returns STATUS. 

tdefine msgMoveCopylconGetStyle MakeMsg(clsMoveCopyIcon, 1) 

typedef struct MOVE_COPY_ICON_STYLE { 



U16 move 


2, 


// private 


copy 


2, 


// private 


drag 


2, 


// drag behavior 


destroyOnSelChange 


1, 


// destroy self on msgSelChangedOwners 


spare 


9; 


// unused (reserved) 



MOVE COPY ICON STYLE, *P MOVE COPY ICON STYLE; 



MCICON.H 473 

Messages from other classes 



msgMoveCopylconSetStyle 

Sets the style values. 

Takes P_MOVE_COPY_ICON_STYLE, returns STATUS. 

♦define msgMoveCopylconSetStyle MakeMsg(clsMoveCopyIcon, 2) 

A&smge typedef struct MOVE_COPY_ICON_STYLE { 

Arguments 



U16 move 


2, 


// private 


copy 


2, 


// private 


drag 


2, 


// drag behavior 


destroyOnSelChange 


1, 


// destroy self on msgSelChangedOwners 


spare 


9; 


// unused (reserved) 



o 

} MOVE_COPY_ICON_STYLE, *P_MOVE_COPY_ICON_STYLE; 2 

Comments Note that changing style.drag is not implemented. --» 

msgMoveCopylconDone 

Sent to the control, client when the icon completes move or copy mode. 

Takes P_MOVE_COPY_ICON_DONE, returns STATUS. Category: client notification. 

tdefine msgMoveCopylconDone MakeMsg(clsMoveCopyIcon, 6) 

Arguments typedef struct MOVE_COPY_ICON_DONE { 

// icon sending msg 
// true for Move, false for Copy 
// destination window to move/copy to 
// point to move/copy to in dest space 
// offset of pen from icon origin (grab point) 
// unused (reserved) 
// unused (reserved) 
// unused (reserved) 
// unused (reserved) 
} MOVE_COPY_ICON_DONE, *P_MOVE_COPY_ICON_DONE ; 

Comments If the client responds with stsRequestDenied, stsMessagelgnored, or a status < stsOK, the 

moveCopylcon will be jumped to pArgs->rect. origin and the single or double marquee will be restarted. 
Otherwise, msgDestroy will be self-sent. 

msgMoveCopylconCancel 

Sent to the control.client when the icon cancels move or copy mode. 

Takes OBJECT, returns STATUS. Category: client notification. 

tdefine msgMoveCopylconCancel MakeMsg(clsMoveCopyIcon, 5) 

Comments clsMoveCopylcon will send self as pArgs. This is sent when style.destroyOnSelChange is true, and 

msgSelChangedOwners is received. 



WIN 


icon; 


BOOLEAN 


move ; 


WIN 


dest; 


XY32 


destXY; 


XY32 


penOffset; 


SIZE32 


iconSize; 


U32 


sparel; 


U32 


spare2 ; 


U32 


spare3 ; 



Messages from other classes 



msglnputEvent 

Notification of an input event. 
Takes P_INPUT_EVENT, returns STATUS. 
Comments If style.drag is not mcDragNone, clsMoveCopylcon responds as follows: 
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If pArgs->devCode is msgPenMoveDown and the pen has moved beyonddefined threshold, or 
pArgs->devCode is msgPenExitDown, an instance ofwill be created to indicate the move/copy. 

If pArgs->devCode is msgPenUp, and msgPenDown has already been seen,is sent to the client. 

msgTrackProvideMetrics 

Sent to a track client before track is created. 

Takes P_TRACK_METRICS, returns STATUS. Category: third-party notification. 

Comments If pArgs->tag is tagMoveCopylconTrack, msgTrackProvideMetrics (pArgs) is sent to the 

moveCopylcon's client. 

msgTrackDone 

Sent by a tracker when it's done. 

Takes P_TRACK_METRICS, returns STATUS. Category: client notification. 

Idefine msgTrackDone MakeMsg(clsTrack, 6) 

Comments clsMoveCopylcon will hit-detect pArgs->curXY to locate the window over which the track was 

dropped. The client will be sent msgMoveCopylconDone with the following 
MOVE_COPY_ICON_DONE parameters: 

icon = self; 

move = true for move, false for copy; 

dest = destination window; 

destXY = pArgs->curXY in dest window's space; 

penOffset = pArgs->curXY in pArgs->rect-relative space; 

msgSelChangedOwners 

Notify the observers when either of the selection owners have changed. 
Takes P_SEL_OWNERS, returns STATUS. 



enfs 



If style.destroyOnSelChange is true, clsMoveCopylcon will send msgMoveCopyIconCancel(sel f) to its 
client followed by msgDestroy to self. 
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This file contains the API definition for clsMenu. 

clsMenu inherits from clsTkTable. 

Menus are collections of menu buttons (each of the latter may have a submenu associated with it, which 
in turn is a collection of menu buttons...). 



♦ifndef MENU_INCLUDED 
♦define MENU_INCLUDED 

♦include <tktable.h> 
♦include <mbutton.h> 



♦ifndef TKTABLE_INCLUDED 

#endif 

♦ifndef MBUTTON_INCLUDED 

♦endif 



Common #defines and typedefs 



typedef OBJECT MENU, *P_MENU; 



Menu Type Styles 



♦define msTypeMenuBar 





// horizontal menu bar 


♦define msTypeMenu 


1 


// pull-down or pull-right 


// 


2 


// unused (reserved) 


// 


3 


// unused (reserved) 



typedef struct MENU_STYLE { 

U16 type : 2, // menu type 

spare : 14; // unused (reserved) 
} MENU STYLE, *P MENU STYLE; 



Messages 



msgNew 

Creates a menu window, together with the child windows specified in pEntries. 

Takes P_MENU_NEW, returns STATUS. Category: class message. 

irguments typedef struct MENU_NEW_ONLY { 

MENU_STYLE style; // overall style 

MENU_BUTTON_NEW menuButtonNew; // storage for default child new struct 
U32 spare; // unused (reserved) 

} MENU_NEW_ONLY, *P_MENU_NEW_ONLY; 

♦define menuNewFields \ 

tkTableNewFields \ 
MENU_NEW_ONLY menu; 

typedef struct MENU_NEW { 

menuNewFields 
} MENU_NEW, *P_MENU_NEW; 

:omme«ts If pArgs->menu. style. type is msTypeMenu, the following is done before ObjectCallAncestor(): 
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pArgs->win. flags. style |= wsSaveUnder; 
pArgs->win. flags. style |= wsClipSiblings; 
pArgs->win . flags . style &= ~ (U32 ) wsParentClip; 

pArgs->border. style. shadow = bsShadowThinBlack; 
pArgs->border. style. shadowGap = bsGapTransparent; 

pArgs->border. style. leftMargin = bsMarginMedium; 

pArgs->border . style . rightMargin = bsMarginMedium; 

pArgs->border.style.bottomMargin = bsMarginMedium; 

pArgs->border.style.topMargin = bsMarginMedium; 

pArgs->tableLayout. style. growChildWidth = true; 
pArgs->tableLayout. style. wrap = false; 

pArgs->tableLay out. numRows. constraint = tllnfinite; 

pArgs->tableLayout.numCols. constraint = tlAbsolute; 

pArgs->tableLayout.numCols. value = 1; 

pArgs->tableLayout.colWidth. constraint = tlChildrenMax; 

msgNewDefaults 

Initializes the MENU_NEW structure to default values. 

Takes P_MENU_NEW, returns STATUS. Category: class message. 

Message typedef Struct MENU_NEW { 

Arguments menuNewFields 

} MENU_NEW, *P_MENU_NEW; 

Comments Zeroes out pArgs->menu and sets 

pArgs->win. flags. style |= wsFileNoBounds; 

pArgs->embeddedWin. style. selection = ewSelectPreserve; 

pArgs->gWin. style. gestureEnable = false; 

pArgs ->border. style. edge = bsEdgeAll; 
pArgs->border. style. leftMargin = bsMarginMedium; 
pArgs->border. style. rightMargin = bsMarginMedium; 
pArgs->border.style.bottomMargin = bsMarginSmall; 
pArgs->border.style.topMargin = bsMarginMedium; 

// layout for msTypeMenuBar 

pArgs->tableLayout. style. growChildWidth = false; 
pArgs->tableLayout. style. growChildHeight = false; 
pArgs->tableLayout. style. wrap = true; 

pArgs->tableLayout . colWidth . gap = def aultColGap; 
pArgs->tableLayout . rowHeight . constraint = tlGroupMax; 
pArgs->tableLayout.rowHeight.gap = defaultRowGap; 

pArgs->menu. style. type = msTypeMenuBar; 

The menu is a table of clsMenuButton buttons, so pArgs->tkTable.pButtonNew is set to the address of 
pArgs->menu.menuButtonNew. This menuButtonNew is initialized using msgNewDefaults to 
clsMenuButton, then altered as in msgTkTableChildDefaults. See msgTkTableChildDefaults for more 
info. 

Default Menu style: 

type = msTypeMenuBar 
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Message 
Arguments 



msgMenuGetStyle 

Passes back the current style values. 

Takes P_MENU_STYLE, returns STATUS. 

#define msgMenuGetStyle MakeMsg(clsMenu, 4) 

typedef struct MENU_STYLE { 

U16 type : 2, // menu type 

spare : 14; // unused (reserved) 
} MENU STYLE, *P MENU STYLE; 



Message 
Arqurneni 



Comments 



msgMenuSetStyle 

Sets the style values. 

Takes P_MENU_STYLE, returns STATUS. 

tdefine msgMenuSetStyle MakeMsg(clsMenu, 5) 

typedef struct MENU_STYLE { 

U16 type : 2, // menu type 

spare : 14; // unused (reserved) 
} MENU_STYLE, *P_MENU_STYLE; 

Note: setting style.type is not implemented. 



msgMenuShow 

Puts up or takes down the menu by inserting or extracting it as a child of theRootWindow. 

Takes BOOLEAN, returns STATUS. 

#define msgMenuShow MakeMsg(clsMenu, 1) 

Comments To show the menu, first delta the menu to the desired position, in root window space and use pArgs of 

true. To hide the menu, use pArgs of false. 

Before showing the menu, the menu's origin is altered as follows (in this order): 

♦ If the menu is wider or taller than theRootWindow, the menu will be placed in an instance of 
clsScrollWin to allow the user to scroll through the menu contents. 

If the menu falls off the right edge of the root window, the menu is right-justified. 

If the menu falls off the left edge of the root window, the menu is left-justified. 

If the menu falls below the bottom edge of the root window, the menu is bottom-justified. 

If the menu falls above the top edge of the root window, the menu is top-justified. 



The menu will insert itself as an input filter when shown, and remove itself when hidden. The menu 
will be extracted from the root window when hidden. 



msgMenuDone 

Sent via msgWinSend to the manager when the menu is "done". 

Takes WIN, returns STATUS. Category: manager notification. 

♦define msgMenuDone MakeMsg(clsMenu, 2) 

Comments The manager should use msgMenuShow to take down the menu. See msgWinSend for clsMenu's 

response to msgMenuDone via msgWinSend. 
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msgMenuAdjustSections 

Adjusts the border edges and margins of children to correctly reflect a sectioned menu. 

Takes BOOLEAN, returns STATUS. 

#define msgMenuAdjustSections MakeMsg (clsMenu, 3) 

This message is provided for compatibility and results in a self-send of msgTblLayoutAdjustSections. 
New clients should use msgTblLayoutAdjustSections directly. 

msgTblLayoutAdjustSections 



Messages from other classes 



msgTkTableChildDefaults 

Sets the defaults in pArgs for a common child. 

Takes PJJNKNOWN, returns STATUS. 

Comments clsMenu sets up defaults for each child as follows: 

pArgs->win. flags. style |= wsParentClip; 

pArgs->win . flags . style &= ~ (U32 ) (wsClipSiblings | wsClipChildren) ; 

If the child is a descendant of clsBorder, then 

pArgs->border. style. backgroundlnk |= bsInkExclusive; 
If the child is a descendant of clsButton, then 

pArgs->butt on. style. manager = bsManagerParent; 

msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments clsMenu receives input events as a result of the InputFilterAdd() done during msgMenuShow. The 

events are handled as follows: 

♦ If pArgs->destination is self, stsInputSkip returned. 

♦ If pArgs->destination is a descendant of self (i.e. in the menu's window tree), the event is passed 
through to the destination by returning stsInputSkip. 

♦ If the pArgs->devCode is msgPenDown, clsMenu will ObjectCallAncestor() msgWinSend with 
the following WIN_SEND parameters: 

msg = msgMenuDone; 
data[0] = pArgs->destination; 
flags = wsSendDe fault; 
lenSend = SizeOf (WIN_SEND) ; 

This is intended as a notification to the menu's manager that themenu is ready to be taken down. If 

pArgs->destination is a descendant of clsMenuButton, stsInputContinue is returned to allow the 

input event to continue; otherwise, the event is terminated by returning 

stsInputTerminateRemoveStroke. 

♦ All other input events result in a return status of stsInputContinue. 
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Messages from other classes 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes WIN_SEND, returns STATUS. 

Comments clsMenu looks for manager notifications of msgMenuDone or msgButtonDone via msgWinSend. 

If pArgs->msg is msgMenuDone and pArgs->data[0] is a descendant of self, clsMenu will return stsOK. 
This prevents sel f s manager from receiving the msgMenuDone and taking down the menu. This 
prevents, for example, a pull-right menu coming down from taking down its main menu. 

If pArgs->msg is msgButtonDone, pArgs->msg is replaced with msgMenuDone before calling o 

ObjectCallAncestorQ. This results, for example, in the menu coming down when a button in the menu 



is hit. 

All other values of pArgs->msg result in ObjectCallAncestorQ. 
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MFILTER.H 



This file contains the API for clsModalFilter. 

clsModalFilter inherits from clsObject. 

Modal filters implement window-relative input modality. 

Modal filters are useful for making a window tree behave in a modal fashion: the user must interact with 
the windows in the tree (and make it go away) before they can use other windows in the application (or 
system). 

Here is an example of how to set up a modal filter object: 

MODAL_FILTER_NEW mfn; 

// Create it. 

ObjCallWarn(msgNewDefaults, clsModalFilter, fcmfn) ; 

mfn.modalFilter. flags = Appropriate flags>; 

mfn.modalFilter. process = OSThisProcessO ; 

mfn.modalFilter. subTreeRoot = <root of window tree to make modal>; 

Ob jCallRet (msgNew, clsModalFilter, &mfn, s) ; 

// Activate it. 

ObjCallRet (msgModalFilterActivate, mfn.object.uid, pNull, s); 

// Tell input system about it. 
StsRet (InputFilterAdd ( \ 

mfn.object.uid, inputAHRealEventsFlags, 0, <priority>) , s) ; 

See input.h for a discussion of filter priorities and tips on choosing a priority. 



Debugging Flags 

The clsModalFilter debugging flag is 'K\ Defined values are: 
flaglO (0x0400) general 



♦ifndef MFILTER_INCLUDED 
♦define MFILTER_INCLUDED 

♦include <clsmgr.h> 
♦include <ostypes.h> 
♦include <win.h> 



♦ifndef CLSMGR_INCLUDED 

♦endif 

♦ifndef OSTYPES_INCLUDED 

tendif 

#ifndef WIN_INCLUDED 

tendif 



Common #defines and typedefs 



typedef OBJECT MODAL_FILTER, *P_M0DAL_FILTER; 

// Flags 

♦define mfSystemModal flagO 

♦define mfAutoDismiss flagl 

♦define mfDefaultFlags mfAutoDismiss 
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typedef struct MODAL_FILTER_METRICS { 

U16 flags; 

OS_TASK_ID process; // app process for filter; ignored for mfSystemModal 

WIN subTreeRoot; // window tree to which to give events 

U32 spare; // reserved 
} MODAL FILTER METRICS, *P MODAL FILTER METRICS; 



msgNew 

Creates a modal filter. 

Takes P_MODAL_FILTER_NEW, returns STATUS. Category: class message. 

typedef MODAL_FILTER_METRICS MODAL_FILTER_NEW_ONLY, *P_MODAL_FILTER_NEW_ONLY; 

fdefine modalFilterNewFields \ 

objectNewFields \ 

MODAL_F I LTER_NEW_ONLY modalFi 1 t er ; 

Arguments typedef struct MODAL_FILTER_NEW { 

modalFilterNewFields 
} MODAL_FILTER_NEW, *P_MODAL_FILTER_NEW; 

Comments The fields you commonly set are: 

pArgs->modalFilter.flags appropriate flags 

pArgs->modalFilter.process process owning the window tree 

pArgs->modalFilter.subTreeRoot root of window tree for which to filter 

A filter is active after msgNew, and becomes deactivated only after it has dismissed its window. 



msgNewDefaults 

Initializes the MODAL_FILTER_NEw* structure to default values. 

Takes P_MODAL_EILTER_NEW, returns STATUS. Category: class message. 

Message typedef struct MODAL_FILTER_NEW { 

Arguments modalFilterNewFields 

} MODAL_FILTER_NEW, *P_MODAL_FILTER_NEW; 

Comments Zeroes out pArgs->modalFilter and sets: 

pArgs->modalFilter. flags = mfDefaultFlags; 



msgModalFilterGetFlags 

Passes back the receiver's flags. 
Takes PJJ16, returns STATUS. 
tdefine msgModalFilterGetFlags MakeMsg(clsModalFilter, 1) 



msgModalFilterSetFlags 

Sets the receiver's flags. 

Takes P_U16, returns STATUS. 

#define msgModalFilterSetFlags MakeMsg(clsModalFilter, 2) 
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Messages from Other Classes 



msgModalFilterActivate 

Activates the filter. 
Takes nothing, returns STATUS. 

#define msgModalFilterActivate MakeMsg(clsModalFilter, 3) 

Comments A filter is active after msgNew, and becomes deactivated only after it has dismissed its window. 



msgModalFilterDeactivate 

Deactivates the filter. 

Takes nothing, returns STATUS. 



3 

#define msgModalFilterDeactivate MakeMsg(clsModalFilter, 4) ^. 

Comments A filter is active after msgNew, and becomes deactivated only after it has dismissed its window. 

msgModalFilterDismissWin 

Sent to the subTreeRoot if the win should be dismissed. 

Takes nothing, returns STATUS. Category: third-party notification, 
tdefine msgModalFilterDismissWin MakeMsg(clsModalFilter, 5) 



Messages from Other Classes 



msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments If the filter is inactive, or the input event's devCode is not of clsPen, or the evfGrabTracker flag is set in 

pArgs->flags, or there's a grabber object present (InputGetGrab), then the filter just returns 
stsInputContinue. 

Next, if the pArgs->destination is not a valid object, the filter returns stsInputTerminate. 

If, at this point, the mfSystemModal flag is clear and the process of the pArgs->destination doesn't 
match MODAL_FILTER_METRICS.process, the filter does the following: 

if mfAutoDismiss is on 

if the pArgs->devCode is msgPenDown 
self -send msgModalFilterDeactivate 
send msgModalFilterDismissWin to MODAL_FILTER_METRICS . subTreeRoot 

(and if that returns an error status, top and flash subTreeRoot) 
return stsInputTerminate. 
otherwise return stsInputContinue. 
otherwise return stsInputContinue. 

Now, if pArgs->destination is within subTreeRoot, return stsInputSkipTo4. (See input.h) 

Next, if the subTreeRoot is not a valid object, return stsFailed. 

Next, if mfAutoDismiss is on and pArgs->devCode is msgPenDown: 

self -send msgModalFilterDeactivate 

send msgModalFilterDismissWin to MODAL_FILTER_METRICS . subTreeRoot 

(and if that returns an error status, top and flash subTreeRoot) 
return stsInputTerminate. 
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Finally, if pArgs->devCode is msgPenDown, the filter tops the subTreeRoot, flashes it, and returns 
stsInputTerminate. 

Return v«iwe stsInputContinue 

See Also msgWinlnsert used by a filter to top the subTreeRoot 

msgBorderFlash used by a filter to flash the subTreeRoot 
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NOTE.H 



This file contains the API for clsNote. 

clsNote inherits from clsFrame. 

Provides the UI for system- and app-modal messages to the user. 



Ppr Debugging Flags 



The clsNote debugging flag is 'K'. Defined values are: 
flag 15 (0x8000) general 

#ifndef NOTE_INCLUDED 
tdefine NOTE_INCLUDED 

♦include <clsmgr.h> 
tinclude <win.h> 
♦include <frame.h> 
♦include <tktable.h> 



#ifndef CLSMGR_INCLUDED 

#endif 

tifndef WIN_INCLUDED 

tendif 

tifndef FRAME_INCLUDED 

tendif 

tifndef TKTABLE_INCLUDED 

#endif 



Common #defines and typedefs 

typedef WIN NOTE, *P_N0TE; 

// Tags of component windows within a note. 



tdefine tagNoteTitle 
tdefine tagNoteTkTable 
tdefine tagNoteCmdBar 

// Note flags 
tdefine nfSystemModal 
tdefine nfAutoDestroy 
tdefine nfSystemTitle 
tdefine nfAppTitle 



MakeTag (clsNote, 1) 
MakeTag (clsNote, 2) 
MakeTag (clsNote, 3) 



flagO 
flagl 
flag2 
flag3 



// use system title; ignore pTitle 

// use app title; ignore pTitle 

// use pTitle as is (not "Note from <pTitle>") 

// dismiss on timeout or input 

// don't word wrap content labels 

// pContentEntries is P_NOTE_RES_ID 

// disable prefs-controlled beeping 

// note will ignore cmdBar buttons 



tdefine nfUnformattedTitle flag9 

tdefine nfTimeout flag4 

tdefine nfNoWordWrap flag5 

tdefine nfResContent flag6 

tdefine nfNoBeep flag7 

tdefine nfExplicitCancel flag8 

tdefine nfDefaultSysFlags \ 

(nfSystemModal | nfAutoDestroy | nfSystemTitle | nfNoBeep) 

tdefine nfDefaultAppFlags (nfAppTitle | nfNoBeep) 

tdefine nfDefaultFlags nfDefaultSysFlags 

typedef struct NOTE_METRICS { 

// looks and filter flags 

// returned iff win dismissed 

// filter or objNull for default 

// timeout or for user pref 

// client for msgNoteDone 

// reserved 

} NOTE METRICS, *P NOTE METRICS; 



U16 


flags ; 


MESSAGE 


au t oD i smi s sMs g ; 


OBJECT 


modalFilter; 


OS_MILLISECONDS 


timeout; 


OBJECT 


client; 


U32 


spare; 
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msgNew 

Creates a note. 

Takes P_NOTE_NEW, returns STATUS. Category: class message. 

typedef struct { 

NOTE_METRICS metrics; 

P_CHAR pTitle; 

P_UNKNOWN pContentEntries; // used to create the content 

P_TK_TABLE_ENTRY pCmdBarEntries; // used to create the command bar 

U32 spare; // reserved 

} NOTE_NEW_ONLY, *P_NOTE_NEW_ONLY; 

If nfSystemModal is on, then the client is ignored. If nfSystemModal is off, then msgNoteShow returns 
immediately, and the client will be sent msgNoteDone when the note is dismissed. 

If pTitle will be used (nfSystemTitle and nfAppTitle are off), the title will appear as follows: 

"Note from <pTitle>..." if nfUnformattedTitle is off 

"<pTitle>" if nfUnformattedTitle is on 

tdefine noteNewFields \ 
frameNewFields \ 

NOTE_NEW_ONLY note; 

typedef struct NOTE_NEW { 

noteNewFields 
} NOTE_NEW, *P_N0TE_NEW; 

typedef struct { 

RES_ID resld; // resld for a string table resource 

U32 index; // index within that table of a string 

U32 spare; // reserved (unused) 

} NOTE_RES_ID, *P_NOTE_RES_ID; 

clsNote will use msgResReadData to read the string from either OSThisAppO's APP_METRICS.resList, 
or theSystemResFile if OSThisAppO returns objNull. 

Since clsNote will make a label from the string and clsLabel will break word-wrapped labels at newlines 
('\n'), you may embed newlines in the string to force line breaks. 

The fields you commonly set are: 

pArgs->note.flags appropriate flags 

pArgs->note.autoDismissMsg arg for msgNoteCancel 

pArgs->note.timeout timeout if desired 

pArgs->note.client client if app-modal 

clsNote will create all the appropriate interior windows, then self-send msgWinLayout to size and place 
all the windows. .After that, if either the x or y of the note's origin is 0, clsNote will delta the new 
instance so that when it is inserted as a child of theRootWindow the note will appear in a reasonable 
location. 

To display and activate the note, use msgNoteShow. 
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msgNewDefaults 

Initializes the NOTEJSTEW structure to default values. 

Takes P_NOTE_NEW, returns STATUS. Category: class message. 



Message typedef struct NOTE_NEW { 

^rgumersts noteNewFields 

} NOTE NEW, *P NOTE NEW; 



Zeroes out pArgs->note and sets: 

pArgs->win . flags . style 

|= wsSaveUnder | wsShrinkWrapWidth | wsShrinkWrapHeight; O 



pArgs->border. style. resize = false; 
pArgs->border. style. drag = bsDragNone; 
pArgs->customLayout. style. limitToRootWin = true; 
pArgs->frame. style. closeBox = false; 
pArgs->frame. style. zoomable = false; 

pArgs->note. metrics. flags = nfDefaultFlags; 

msgNoteGetMetrics 

Get the metrics of a note. 

Takes P_NOTE_METRICS, returns STATUS. 

tdefine msgNoteGetMetrics MakeMsg(clsNote, 1) 

typedef struct NOTE_METRICS { 
rgyments U16 flags; // looks and filter flags 

// returned iff win dismissed 
// filter or objNull for default 
// timeout or for user pref 
// client for msgNoteDone 
// reserved 

} NOTE METRICS, *P NOTE METRICS; 



U16 


flags; 


MESSAGE 


autoDismissMsg; 


OBJECT 


modalFilter; 


OS_MILLISECONDS 


timeout ; 


OBJECT 


client; 


U32 


spare; 



msgNoteSetMetrics 

Set the metrics of a note. 

Takes P_NOTE_METRICS, returns STATUS. 

tdefine msgNoteSetMetrics MakeMsg(clsNote, 2) 

typedef struct NOTE_METRICS { 

// looks and filter flags 

// returned iff win dismissed 

// filter or objNull for default 

// timeout or for user pref 

// client for msgNoteDone 

// reserved 

} NOTE_METRICS, *P_NOTE_METRICS ; 

clsNote will destroy any previous filter object if the filter is changed. 



rgumemts 


U16 


flags ; 




MESSAGE 


autoDismissMsg; 




OBJECT 


modalFilter; 




OS_MILLISECONDS 


timeout; 




OBJECT 


client; 




U32 


spare ; 



msgNoteShow 

Displays a note. 

Takes P_MESSAGE, returns STATUS. 

tdefine msgNoteShow MakeMsg (clsNote, 3) 



488 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 

Comments If nfSystemModal is on, then the send of this message will block until the note is dismissed. At that 

time, msgNoteShow will set *pArgs to the message sent by the button that was hit (or autoDismissMsg 
if the win was dismissed by its modal filter). Be aware that the entire input system (and therefore the 
window system) will be blocked while msgNoteShow is waiting for completion. 

If nfSystemModal is off, then msgNoteShow returns immediately. It is the app's responsibility to 
implement whatever notion of "modality" is appropriate. Usually this means remembering that the app 
should be "modal" and waiting for msgNoteDone to be sent to the note's client (which should usually 
be the app object). Although the note will filter all the input to the app and discard that input not 
directed at the note, the app must still respond to messages from the app framework. When 
nfSystemModal is off, the *pArgs to msgNoteShow is not set. 

msgNoteDone 

This is the message sent to clients when a note is dismissed. 

Takes MESSAGE, returns STATUS. 

tdefine msgNoteDone MakeMsg(clsNote, 4) 

Comments msgNoteDone is only sent if nfSystemModal is off. 

The parameter message is the message sent by the button that was hit (or autoDismissMsg if the win 
was dismissed by its modal filter). 



msgNoteCancel 

Informs a note that it should take itself down. 
Takes P_MESSAGE, returns STATUS. 
tdefine msgNoteCancel MakeMsg(clsNote, 5) 

Comments This will be posted to a note when: 

♦ it receives msgButtonNotify from its command bar, or 

♦ it receives msgModalFilterDismissWin from its filter. 

The method code will do all the final cleanup, including extracting the note window (and destroying it 
if nfAutoDestroy was on). The *pArgs message will either be returned to the original code that called 
msgNoteShow (if nfSystemModal is on), or passed to msgNoteDone (if nfSystemModal is off). 

This message is only interesting to subclasses of clsNote. It should not be used by normal clients. 

y Messages from Other Classes 

msgFree 

Sent as the last of three msgs to destroy an object. 

Takes OBJJCEY, returns STATUS. 

Comments clsNote will use InputFilterRemove() to take its filter out of the input system's list of filters if the filter is 

active. clsNote will then send msgDestroy to its filter if the note had created it (as opposed to the client 
passing in a filter). 
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Comments 



Comments 



See Also 



msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

clsNote will restore its flags, autoDismissMsg, and timeout. 



msgSave 

Causes an object to file itself in an object file. 
Takes P_OBJ_SAVE, returns STATUS. 
Comments clsNote will file its flags, autoDismissMsg, and timeout. It will not file its modalFilter or client. 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes P_WIN_SEND, returns STATUS. 

Comments The note may respond by posting itself msgNoteCancel (passing a pointer to its autoDismissMsg), 

depending on the pArgs->msg and the nffixplicitCancel flag. 

msgWinLayoutSelf 

Tells a window to layout its children (sent during layout). 

Takes P_WIN_METRICS, returns STATUS. 

Comments If wsLayoutResize is on and nfNoWordWrap is off and the note is shrinkwrapping in width, the note 

might further adjust the results of the default layout (obtained by just calling ancestor). The note's width 
will be forced wider if the height of the initial layout is taller than dictated by the 'golden section ratio 
ofh/w= 0.618. 



msgGWinGesture 

Self-sent to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

clsNote will just return the result of calling its ancestor if the note has buttons (i.e., NOTE_NEW_ONLY 
had a non-null pCmdBarEntries). 

Otherwise, the note will post itself msgNoteCancel, passing a pointer to its autoDismissMsg. Although 
clsNote should check the rifExplicitCancel flag, it does not yet do so for msgGWinGesture (although 
this may change in the future). 

msgNoteCancel tells a note to take itself down. 



Comments 



msgModalFilterDismissWin 

Sent to the subTreeRoot if the win should be dismissed. 

Takes nothing, returns STATUS. Category: third-party notification. 

The note will respond by posting itself msgNoteCancel, passing a pointer to its autoDismissMsg. 
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msgTimerNotify 

Notifies the client that the timer request has elapsed. 

Takes P_TIMER_NOTIFY, returns nothing. Category: advisory message. 

Comments A note may receive this when a non-zero NOTE_METRICS.timeout was specified and the note was 

displayed via msgNoteShow. If this msgTimerNotify does indeed signify that the note should take itself 
down, the note will do so by posting itself msgNoteCancel (passing a pointer to its autoDismissMsg). 
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OPTION.H 



This file contains the API for clsOption. 

clsOption inherits from clsFrame. 

Provides the standard looks, behavior, and protocol of option sheets. 

An option sheet is a special kind of frame that you can use to display the properties of a selected object. 
If the selected object has several different sets of properties, then the option sheet will have several 
windows stacked in it like a deck of cards. Each of these windows is called an option card. For more 
information on option cards, please see clsOptionTable (in opttable.h). 

The user navigates between the option cards with a popup choice, which is available on the title line of 
the option sheet. The popup choice contains a clsTabButton for each option card. The typical PenPoint 
developer does not need to know about how option sheets use clsTabButton, but feel free to take a look 
at it (in tbutton.h). 

Although clsOption provides a rich API, most PenPoint developers need to understand only the 
following: 

Messages sent by a client to an option sheet: 

msgOptionAddCard 

msgOptionAddLastCard 

Messages sent to a sheet's client by an option sheet: 

msgOptionClosed 

msgOptionProvideTopCard 

Messages sent to a card s client by an option sheet: 

msgOptionProvideCardWin 

msgOptionApplyCard 

msgOptionRefreshCard 

msgOptionApplicableCard 

Messages self-sent by a client to create an option sheet: 

msgOptionCreateSheet 

msgOptionAddCards 
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Debugging Flags 

The clsOption debugging flag is '%'. Defined values are: 
flag8 (0x0100) general 



#ifndef OPTION_INCLUDED 
♦define OPTION_INCLUDED 

♦include <frame.h> 
♦include <tktable.h> 



tifndef FRAME_INCLUDED 

♦endif 

tifndef TKTABLE_INCLUDED 

tendif 



Common #defines and typedefs 



♦define tagOptionApplyButton 
♦define tagOptionApplyAndCloseButton 
♦define tagOptionCloseButton 

♦define hlpOptionApplyButton 
♦define hlpOptionApplyAndCloseButton 
♦define hlpOptionCloseButton 

typedef OBJECT OPTION; 



MakeTag (clsOption, 1) 
MakeTag (clsOption, 2) 
MakeTag (clsOption, 3) 

tagOptionApplyButton 

tagOptionApplyAndCloseButton 

tagOptionCloseButton 



Sheet Modality Style 

The sheet modality style specifies whether the card is modal, and if so, whether system-modal or 
application-modal. 

♦define osModalNone 
♦define osModalApp 1 
♦define osModalSystem 2 

Card Navigation Style 

The card navigation style specifies how the user can move between option cards. GO recommends that 
you use a popup choice. 

// popup choice in the title bar 
// tab buttons in the tab bar 
// unused (reserved) 
// unused (reserved) 

// observe theSelectionManager 
// whether modal, and what type 
// card navigation style 

// true => enable msgOptionAddCards protocol 
// true => current list of cards is invalid 
// true => current top card is invalid 
// true => hide card navigation 
// unused (reserved) 
// unused (reserved) 
•I0N_STYLE; 

Default OPTION_STYLE: 

senseSelection = true 



♦define 


osNavPopup 


♦define 


osNavTabBar 1 


// 


2 


// 


3 


typedef 


Struct 0PTI0N_STYLE { 


U16 


senseSelection 


1, 




modality 


2, 




cardNav 


2, 




getCards 


1, 




needCards 


1, 




needTopCard 


1, 




hideNav 


1, 




sparel 


7; 


U16 


spare2 


16; 


} 0PTI0N_STYLE, *P_0PTI01 


^ STYLE; 



modality 


= osModalNone 


cardNav 


= osNavPopup 


getCards 


= false 


needCards 


= true 


needTopCard 


= true 


hideNav 


= false 
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typedef struct OPTION CARD { 




OPTION 


option; // 


out 


U32 


tag; // 


in: 


WIN 


win; // 


in: 


P CHAR 


pName; // 


in: 


016 


nameLen; // 


in: 


OBJECT 


client; // 


in: 


032 


clientData[2] ; // 


in: 


032 


spare 1; // 


unu 


032 


spare2; // 


unu 


} OPTION CARD, *P OPTION CARD; 




typedef struct OPTION TAG { 




OPTION 


option; 




TAG 


tag; 




} OPTION TAG, *P OPTION TAG; 





option sheet sending the msg. 
tag for tab 
card window or objNull 
card name 

max. len for pName (for msgOptionGetCardAndName) 
for msgOptionRefreshCard, etc. 
arbitrary client data 
unused (reserved) 
(reserved) 



Messages 



msgNew 

Creates an option sheet. 

Takes P_OPTION_NEW, returns STATUS. Category: class message. 

Argyments typedef struct 0PTI0N_NEW_0NLY { 

0PTI0N_STYLE style; // overall style 

P_TK_TABLE_ENTRY pCmdBarEntries; // optional override 

032 sparel; // unused (reserved) 

032 spare2; // unused (reserved) 

} 0PTI0N_NEW_0NLY, *P_0PTI0N_NEW_0NLY; 

If pCmdBarEntries is not null, then it should be the address of a null-terminated array of entries. It is 
used to create a custom command bar rather than the usual Apply and Apply&Close buttons. The client 
of this custom command bar is set to the frame's client. 

♦define optionNewFields \ 
frameNewFields \ 

0PTI0N_NEW_0NLY option; 

typedef struct 0PTI0N_NEW { 

optionNewFields 
} 0PTI0N_NEW, *P_0PTI0N_NEW; 

Comments If pArgs->option.style.cardNav is osNavPopup, clsOption will create an instance of clsTkTable with a 

label and a popupChoice in it as the frame s title bar. The label string will be set to the frame's title 
string. The popup choice will contain a choice for each card in the option sheet. 

msgNewDefaults 

Initializes the OPTION_NEW structure to default values. 

Takes P_OPTION_NEW, returns STATUS. Category: class message. 



Message typedef Struct 0PTI0N_NEW { 

Arguments optionNewFields 

} 0PTI0N_NEW, *P_0PTI0N_NEW; 

Zeroes out pArgs->option and sets 



pArgs->win. flags. style |= wsSendGeometry | wsSaveOnder; 
pArgs->embeddedWin.style.selection = ewSelectPreserve; 
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pArgs->border.style.shadow = bsShadowThickGray;>border.style.resize = 

bsResizeBottom;>border.style.drag = bsDragDown;>border.style.backgroundInk = 
bsInkGray33;>border.style.edge = bsEdgeAll;>border.style.leftMargin = 

bsMarginMedium;>border.style.rightMargin = bsMarginMedium;>border.style.bottomMargin = 
bsMarginMedium;>border.style.topMargin = bsMarginLarge; 

pArgs->frame.style.clipBoard = true;>frame.style.closeBox = false;>frame.style.zoomable = 
false;>frame.style.cmdBar = true; 

pArgs->option.style.senseSelection = true;>option.style.needCards = true;>option.style.needTopCard = 
true;>option.style.cardNav = osNavPopup; 

msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments The option sheet saves its style and the tag of the current top card. This tag is used as the default value 

for the top card when msgOptionProvideTopCard is next sent (e.g., after the option sheet is restored 
and inserted in the window tree). 

Saving an option sheet causes msgSave to be sent to each of the option card's tab buttons. If a card's 
client is OSThisAppO, its tab button records and saves this fact. Otherwise, the client is not saved. 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments The option sheet restores its instance data and sets the following: 

style.neecTropCard = true;.needCards = true; 

If the restored frame has a command bar, msgTkTableSetClient is sent to it to force its client to be the 
option sheet. 

If style.getCards and style.senseSelection are true, the option sheet is set up to observe 
theSelectionManager. 

Restoring an option sheet causes msgRestore to be sent to each of the option card's tab buttons. If a 
card's client was OSThisAppO, its tab button sets the client to the new value for OSThisAppO . Other 
cards have their client set to objNull. 

msgOptionGetStyle 

Passes back the style of the option sheet. 

Takes P_OPTION_STYLE, returns STATUS. 

fdefine msgOptionGet Style MakeMsg(clsOption, 1) 



Mes$o§e typedef struct OPTION_STYLE { 

Arguments 



U16 senseSelection 


1, 


modality 


2, 


cardNav 


2, 


getCards 


1, 


needCards 


1, 


needTopCard 


1, 


hideNav 


1, 


spare 1 


7; 


U16 spare2 


16; 



// observe theSelectionManager 

// whether modal, and what type 

// card navigation style 

// true => enable msgOptionAddCards protocol 

// true => current list of cards is invalid 

// true => current top card is invalid 

// true => hide card navigation 

// unused (reserved) 

// unused (reserved) 



} OPTION STYLE, *P OPTION STYLE; 



Comments 
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Most clients do not need to deal with this message. 



Messoge 
Argymenfs 



Comments 



msgOptionSetStyle 

Sets the style of the option sheet. 

Takes P_OPTION_STYLE, returns STATUS. 

tdefine msgOptionSetStyle MakeMsg(clsOption, 2) 



typedef struct OPTION_STYLE { 



U16 senseSelection 



modality 


2, 


// 


cardNav 


2, 


// 


getCards 


1, 


// 


needCards 


1, 


// 


needTopCard 


1, 


// 


hideNav 


1, 


// 


spare 1 


7; 


// 


U16 spare2 


16; 


// 



1, 



// 



observe theSelectionManager 

whether modal, and what type 

card navigation style 

true => enable msgOptionAddCards protocol 

true => current list of cards is invalid 

true => current top card is invalid 

true => hide card navigation 

unused (reserved) 

unused (reserved) 



} OPTION_STYLE, *P_OPTION_STYLE; 

Note that changing style.cardNav is not supported. 

Most clients do not need to deal with this message. 



Comments 



Comments 



Arguments 



msgOptionGetNeedCards 

Passes back the value of style.needCards. 

Takes P_BOOLEAN, returns STATUS. 

#define msgOptionGetNeedCards MakeMsg(clsOption, 34) 

Most clients do not need to deal with this message. 



msgOptionSetNeedCards 

Sets style.needCards. 

Takes BOOLEAN, returns STATUS. 

#define msgOptionSetNeedCards MakeMsg(clsOption, 35) 

If style.needCards and style.getCards are true, the option sheet self-sends msgOptionGetCards when 
the current cards are needed. 

Most clients do not need to deal with this message. 



msgOptionGetCard 

Passes back some information about a card in the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

#define msgOptionGetCard MakeMsg (clsOption, 3) 



typedef struct OPTION CARD { 



OPTION 


option; 


U32 


tag; 


WIN 


win; 


P CHAR 


pName; 


U16 


nameLen; 


OBJECT 


client; 


U32 


clientData[2] ; 


U32 


spare 1; 


U32 


spare2 ; 



// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 



} OPTION CARD, *P OPTION CARD; 
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Comments In parameters: 

tag tag of the card to get. 

Out parameters: 

win uid of the card. 

client client of the card. 

Will return stsBadParam if a card matching the passed tag was not found in the option sheet. 

Most clients do not need to deal with this message. 

msgOptionGetTopCard 

Passes back some information about the top card in the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

♦define msgOptionGetTopCard MakeMsg(clsOption, 25) 

Messoge typedef struct OPTION_CARD { 

Arguments OPTION option; // out: option sheet sending the msg. 

U32 tag; // in: tag for tab 

WIN win; // in: card window or objNull 

P_CHAR pName; // in: card name 

U16 nameLen; // in: max. len for pName (for msgOptionGetCardAndName) 

OBJECT client; // in: for msgOptionRefreshCard, etc. 

U32 clientData[2] ; // in: arbitrary client data 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} OPTION_CARD, *P_OPTION_CARD; 

Comments Out parameters: 

tag tag of the top card. 

win uid of the card. 

client client of the card. 

If there is no top card, the option sheet sets all of the out parameters to null. 

Most clients do not need to deal with this message. 

msgOptionGetCardAndName 

Passes back some information about a card in the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

tdefine msgOptionGetCardAndName MakeMsg(clsOption, 20) 

Message typedef struct OPTION_CARD { 
rgymenfs OPTION option; // out: option sheet sending the msg. 

// in: tag for tab 
// in: card window or objNull 
// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 
// in: for msgOptionRefreshCard, etc. 
// in: arbitrary client data 
// unused (reserved) 
// unused (reserved) 
} OPTION CARD, *P OPTION CARD; 



OPTION 


option; 


U32 


tag; 


WIN 


win; 


P CHAR 


pName ; 


U16 


nameLen; 


OBJECT 


client; 


U32 


clientData[2] ; 


U32 


sparel; 


U32 


spare2 ; 
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Comments In parameters: 

tag tag of the card to get. 

pName pointer to a buffer in which to put the card's name. 

nameLen size of pName buffer in bytes (if 0, pName is ignored). 

Out parameters: 

win uid of the card. 

client client of the card. 

pName buffer is filled in with the first nameLen bytes of the name of the card (if was not passed for 
nameLen). 

Will return stsBadParam if a card matching the passed tag was not found in the option sheet. 

Most clients do not need to deal with this message. 



Arguments 



Sentiments 



msgOptionEnumCards 

Enumerates the tags of the cards in the option sheet. 
Takes P_OPTION_ENUM, returns STATUS. 
#define msgOptionEnumCards MakeMsg(clsOption, 33) 

typedef struct 0PTI0N_ENUM { 



U16 



max, 
count ; 



P_TAG pTag; 



U16 



U32 
U32 



next ; 



flags ; 
spare; 



// in = size of pTags[] array 

// in = # to return in array 

//if count > max then memory may be allocated 

// out - # of valid entries in array 

// in = ptr to array of card tags 

// out = if memory was allocated 

// client should free the memory using OSHeapBlockFree ( ) 

//in = to start at beginning 

// OR previous out value to pick up 

// where we left off 

// out = where we left off 

// in = various flags (must be for now) 

// unused (reserved) 



} OPTION ENUM, *P OPTION ENUM; 



This message is sent to enumerate all of the cards that have been added to the option sheet. Typical 
usage is shown below. 



//we have space for 10 card tags 

// we want all the card tags 

// our tag buffer 

// first call to msgOptionEnumCards 

// unused for now 

Ob jCallRet (msgOptionEnumCards, sheet, &oe, s) ; 

// oe.pTag[0 .. oe. count] is the array of card tags 

// ... 

// free any allocated memory when finished with the tags 

if (oe.pTag != cards) 

StsWarn (OSHeapBlockFree (oe .pTag) ) ; 



TAG 


cards [10] ; 


OPTION_ENUM 


oe; 


oe.max 


= 10; 


oe . count 


= maxU16; 


oe.pTag 


= cards; 


oe . next 


= 0; 


oe . flags 


= 0; 



Most clients do not need to deal with this message. 
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msgOptionSetCard 

Changes some of the information of a card in the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

#define msgOptionSetCard MakeMsg(clsOption, 4) 

r 

// out: option sheet sending the msg. 
// in: tag for tab 
// in: card window or objNull 
// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 
// in: for msgOptionRefreshCard, etc. 
// in: arbitrary client data 
// unused (reserved) 
// unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

In parameters: 

tag tag of the card to set. 

client client for the card. 

win window for the card. 

pName pointer to a buffer holding a new name, or pNull to keep the old name. 

The option sheet changes the various parameters of the specified card. To avoid changing the name of 



lessoge 


typedef str 


uct OPTION CAR 


rgements 


OPTION 


option- 




U32 


tag; 




WIN 


win; 




P CHAR 


pName; 




U16 


nameLen; 




OBJECT 


client; 




U32 


clientData[2] 




U32 


spare 1; 




U32 
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the card, set pArgs->pName to pNull. 

Most clients do not need to deal with this message. 



msgOptionAddCard 

Adds a card to the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

♦define msgOptionAddCard MakeMsg(clsOption, 5) 

typedef struct OPTION_CARD { 

OPTION option; // out: option sheet sending the msg. 

U32 • tag; // in: tag for tab 

WIN win; // in: card window or objNull 

P_CHAR pName; // in: card name 

U16 nameLen; // in: max. len for pName (for msgOptionGetCardAndName) 

OBJECT client; // in: for msgOptionRefreshCard, etc. 

U32 clientData[2] ; // in: arbitrary client data 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

In parameters: 

tag tag of the card to set. 

pName pointer to a buffer holding the card's name. 

win window for the card. 

client client for the card. 

clientData any client data you want stored with the card. 
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See Also 



If the card specified by pArgs->tag has already been added to the option sheet, the following is done: 

♦ if pArgs->win is objNull, the window for the card is unchanged. 

♦ otherwise, the current window for the card is destroyed and replacedby pArgs->win. 

♦ if pArgs->pName is not pNull, the new name is used. 

♦ the card client is replaced by pArgs->client. 

Note that the card's tag is also used as the helpld of the tab button representing the card (in the popup 
choice card navigation menu or the tab bar). The caller should insure that quick help exists for the card 
with the card's tag as the helpld. 

Most clients send this message to add a card to an option sheet (if there is more than one card). 

msgOptionAddLastCard 



■i 

8 



Mes$«cje 
Arcjymenfs 



msgOptionAddLastCard 

Adds the last card of a group to the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

#define msgOptionAddLastCard MakeMsg(clsOption, 29) 

typedef struct OPTION_CARD { 

// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

This is the same as msgOptionAddCard, except that the menu button for this card has a line break after 
it. 

Most clients send this message to add the last card to an option sheet. 

msgOptionAddCard 



Comments 



See Abo 
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msgOptionAddFirstCard 

Adds the first card of a group to the option sheet. 

Takes P_OPTION_CARD, returns STATUS. 

♦define msgOptionAddFirstCard MakeMsg(clsOption, 42) 



typedef struct OPTION_CARD { 
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// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 



} OPTION CARD, *P OPTION CARD; 
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Comments This is the same as msgOptionAddCard, except that the menu button for this card has a line break 

before it. 

Most clients don't need to send this message. 

See Also msgOptionAddCard 

msgOptionAddAndlnsertCard 

Adds a card to the option sheet and inserts it into the sheet. 

Takes P_OPTION_CARD, returns STATUS. 

tdefine msgOptionAddAndlnsertCard MakeMsg(clsOption, 17) 

Messoge typedef struct OPTION_CARD { 

Arguments OPTION option; // out: option sheet sending the msg. 

U32 tag; // in: tag for tab 

WIN win; /./ in: card window or objNull 

P_CHAR pName; //in: card name 

U16 nameLen; // in: max. len for pName (for msgOptionGetCardAndName) 

OBJECT client; // in: for msgOptionRefreshCard, etc. 

U32 clientData[2] ; // in: arbitrary client data 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} OPTION_CARD, *P_OPTION_CARD; 

Comments This message is handled exactly as in msgOptionAddCard, including the case in which pArgs->tag has 

already been added to the sheet. 

Normally, msgOptionAddCard does not actually insert the card's window into the option sheet's 
window tree. msgOptionAddAndlnsertCard does insert the window. 

Most clients do not need to deal with this message. 

See Also msgOptionAddCard 

msgOptionRemoveCard 

Removes a card from an option sheet and destroys that card. 

Takes P_OPTION_CARD, returns STATUS. 

tdefine msgOptionRemoveCard MakeMsg(clsOption, 6) 

Messoge typedef struct OPTION_CARD { 

// out: option sheet sending the msg. 
// in: tag for tab 
// in: card window or objNull 
// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 
// in: for msgOptionRefreshCard, etc. 
// in: arbitrary client data 
// unused (reserved) 
// unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

Comments The option sheet removes and destroys the specified card. It also removes the window for the card, but 

does not destroy the window. 

In parameters: 

tag tag of card to remove. 

Will return stsBadParam if a card matching the passed tag was not found in the option sheet. 
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See Also 
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Most clients do not need to deal with this message. 
msgOptionExtractCard 



Message 
Arguments 



msgOptionExtractCard 

Extracts a card's window from an option sheet. 
Takes P_OPTION_CARD, returns STATUS. 

♦define msgOptionExtractCard MakeMsg(clsOption, 19) 

typedef struct OPTION_CARD { 

// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

The option sheet extracts the card's window, but does not destroy it. Note that the tab button for the 
card remains, with its win set to objNull. 

In parameters: 

tag tag of card to extract. 

Out parameters: 

win win of extracted card. 

Will return stsBadParam if a card matching the passed tag was not found in the option sheet. 

Most clients do not need to deal with this message. 

msgOptionRemoveCard 



Comments 



OPTION option; 

U32 tag; 

WIN win; 

P_CHAR pName; 

U16 nameLen; 

OBJECT client; 

U32 clientData[2] 

U32 spare 1; 

U32 spare2; 



See Aiso 



Message 
Arguments 



Comments 



msgOptionShowCard 

Causes the specified card to be displayed as the current card. 

Takes P_OPTION_CARD, returns STATUS. 

♦define msgOptionShowCard MakeMsg(clsOption, 14) 



typedef struct 0PTION_CARD { 
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//out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 



} OPTION_CARD, *P_OPTION_CARD; 

The option sheet sends msgOptionRefreshCard to the card. 

In parameters: 

tag tag of card to show. 
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Out parameters: 

win uidofcard. 

client client of card. 

Will return stsBadParam if a card matching the passed tag was not found in the option sheet. 

Most clients do not need to deal with this message. 



msgOptionShowCardAndSheet 

Causes the specified card to be displayed as the current card. 

Takes TAG, returns STATUS. 

tdefine msgOptionShowCardAndSheet MakeMsg(clsOption, 44) 

Comments The sheet is shown if it is not currently shown. 

The option sheet self-sends msgOptionShowCard(OPTION_CARD.tag = pArgs), followed by 
msgOptionShowSheet. 

Most clients do not need to deal with this message. 

See Also msgOptionShowCard 



msgOptionShowTopCard 

Shows the client-defined top card. 

Takes nothing, returns STATUS. 

tdefine msgOptionShowTopCard MakeMsg(clsOption, 30) 

:omments The option sheet sends msgOptionProvideTopCard to its client with the following OPTION_CARD 

parameters: 

option = uid of the option sheet = tag of the current top card = win of the current top card = pNull 
= = client of the current top card 

The option sheet then shows the new top card specified by OPTION_CARD.tag by self-sending 
msgOptionShowCard. 

Most clients do not need to deal with this message. 

msgOptionGetCards 

Gets the cards from the option sheet's client 

Takes nothing, returns STATUS. 

tdefine msgOptionGetCards MakeMsg(clsOption, 32) 

ZommenH If style. getCards is false, this message is ignored. Otherwise, the option sheet sends 

msgOptionAddCards to its client with the following OPTION_TAG parameters: 

option = uid of the option sheet = tag of the option sheet 

Most clients do not need to deal with this message. 
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msgOptionApply 

Tell the option sheet to initiate the Apply protocol. 

Takes nothing, returns STATUS. 

♦define msgOptionApply MakeMsg(clsOption, 8) 

Comments This message is sent by the sheet's Apply button. The option sheet sends msgOptionApplyCard to the 

top card. 

Most clients do not need to deal with this message. 



D 



msgOptionApplyAndClose 

Tell an option sheet to run the Apply protocol and then close itself. 

Takes nothing, returns STATUS. 

♦define msgOptionApplyAndClose MakeMsg(clsOption, 9) 

This message is sent by the sheet's Apply&Close button. The option sheet: 

sends msgOptionApplyCard to the top card in the sheet, and 

sends msgOptionClosed to the sheet's client. 

Most clients do not need to deal with this message. 



msgOptionRefresh 

Tells an option sheet to refresh its card settings. 

Takes nothing, returns STATUS. 

♦define msgOptionRefresh MakeMsg(clsOption, 21) 

Comments This is sent to an option sheet by the default application code when it receives a forwarded "check" 

gesture. 

If the apply buttons in the command bar are grayed out (i.e., the top card is not applicable), nothing is 
done, and stsOK is returned. 

Otherwise, the option sheet sends msgOptionRefreshCard to its top card. It then marks the other cards 
as needing to be refreshed when shown. 

Most clients do not need to deal with this message. 

msgOptionApplicable 

Tells an option sheet to ask the top card if it is applicable. 

Takes P_BOOLEAN, returns STATUS. 

♦define msgOptionApplicable MakeMsg(clsOption, 37) 

Commertts The option sheet sends msgOptionApplicableCard to its top card. It then marks the other cards as 

needing to be sent msgOptionApplicableCard when shown. 

If the top card is not applicable, the command bar buttons are grayed out. 

If pArgs is not pNull, true is passed back if the top card is applicable; otherwise false is passed back. 

Most clients do not need to deal with this message. 



504 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



msgOptionDirty 

Tells an option sheet to ask the top card to dirty its controls. 

Takes nothing, returns STATUS. 

#define msgOptionDirty MakeMsg(clsOption, 38) 

Comments The option sheet sends msgOptionDirtyCard to its top card. It then marks the other cards as needing 

to be sent msgOptionDirtyCard when shown. 

Most clients do not need to deal with this message. 

msgOptionClean 

Tells an option sheet to ask the top card to clean its controls. 
Takes nothing, returns STATUS. 

tdefine msgOptionClean MakeMsg(clsOption, 39) 

Comments The option sheet sends msgOptionCleanCard to its top card. The other cards are NOT cleaned. 

Most clients do not need to deal with this message. 

msgOptionToggleDirty 

Tells an option sheet to toggle the dirty/clean state of the cards. 

Takes nothing, returns STATUS. 

tdefine msgOptionToggleDirty MakeMsg(clsOption, 40) 

Comments The option sheet sends msgOptionProvideCardDirty to the top card's client to determine the 

dirty/clean state of the top card. If the client responds with stsNotUnderstood, the option sheet sends 
msgBorderGetDirty to the top card's window to determine the dirty/ clean state. 

If the top card is clean, msgOptionDirty is then self-sent; otherwise msgOptionClean is self-sent. 

Most clients do not need to deal with this message. 

msgOptionClose 

Tells an option sheet to close itself. 
Takes nothing, returns STATUS. 

tdefine msgOptionClose MakeMsg(clsOption, 10) 

Comments When a sheet receives msgOptionClose, it sends msgOptionClosed to the sheet's client. 

A sheet self-sends msgOptionClose when it receives msgFrameClose. 
Most clients do not need to deal with this message. 

msgOptionGetCardMenu 

Passes back the card navigation menu. 

Takes P_MENU, returns STATUS. 

tdefine msgOptionGetCardMenu MakeMsg(clsOption, 26) 

Comments A copy of the popup card navigation menu is passed back. The option sheet returns objNull if 

style. cardNav is not osNavPopup. 
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Menu buttons in the navigation menu have option sheet as their client, msgOptionShowCardAndSheet 
as their message, and the appropriate card tag as their data. This causes the sheet being displayed and the 
appropriate card being turned to when the user taps on a menu button. 

The caller must send msgOptionCardMenuDone when finished with the menu. 

Most clients do not need to deal with this message. 

See Also msgOptionShowCardAndSheet 

msgOptionCardMenuDone 5 

Indicates the caller is finished with the card menu. O 

Takes MENU, returns STATUS. 3 

tdefine msgOptionCardMenuDone MakeMsg(clsOption, 27) * 

Comments This message should be sent to an option sheet when the card menu retrieved via 

msgOptionGetCardMenu is no longer needed. 

Most clients do not need to deal with this message. 

V Messages Option Sheets send to each 
card's client 

msgOptionShowSheet 

Asks the client of the option sheet to show the option sheet. 

Takes P_OPTION_TAG, returns STATUS. Category: client responsibility. 

♦define msgOptionShowSheet MakeMsg(clsOption, 28) 

Messoge typedef Struct OPTIONJTAG { 

Arguments OPTION option; 

TAG tag; 

} OPTIONJTAG, *P_OPTION_TAG; 

Comments This message is sent by the option sheet when the user taps on a menu button in the card menu and the 

option sheet is not inserted in the window tree. 

The client should respond by inserting the option sheet into the window tree. 

msgOptionProvideCardWin 

Asks the client of the card to provide the window for the card. 

Takes P_OPTION_CARD, returns STATUS. Category: client responsibility, 
♦define msgOptionProvideCardWin MakeMsg(clsOption, 18) 

Message typedef struct OPTION_CARD { 

Arguments OPTION option; // out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 
} OPTION CARD, *P OPTION CARD; 
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Comments! This message is sent by the option sheet when a card is about to be shown, and the window for the card 

is objNull. 

The card client should set pArgs->win to the desired card window. 

Most clients need to override and handle this message. 

msgOptionProvideTopCard 

Asks the client of the option sheet to provide the tag for the top card. 
Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 

#define msgOptionProvideTopCard MakeMsg(clsOption, 31) 

Messoge typedef struct OPTION_CARD { 

Arguments OPTION option; // out: option sheet sending the msg. 

U32 tag; // in: tag for tab 

WIN win; // in: card window or objNull 

P_CHAR pName; // in: card name 

U16 nameLen; // in: max. len for pName (for msgOptionGetCardAndName) 

OBJECT client; // in: for msgOptionRefreshCard, etc. 

U32 clientData[2] ; // in: arbitrary client data 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} OPTION_CARD, *P_OPTION_CARD; 

Comments This message is sent by the option sheet when the top card must be shown. This can be in response to 

msgOptionShowTopCard or when the option sheet is first inserted. 

The option sheet sends msgOptionProvideTopCard to its client with the following OPTION_CARD 
parameters: 

option = uid of the option sheet = tag of the current top card = win of the current top card = pNull 
= = client of the current top card 

The option sheet's client should set pArgs->tag to the tag for the desired top card. 

Note that only pArgs->tag is used as an out parameter; other changes to pArgs are ignored. 

See Also msgOptionShowTopCard 

asMa8ia»:: i :; o :! O u i jL.y:: i :]::ci:;!;M 

msgOptionProvideCardDirty 

Asks the client of the card to provide the dirtiness of the card window. 

Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 

#define msgOptionProvideCardDirty MakeMsg(clsOption, 41) 

Messoge typedef struct OPTION_CARD { 

Arguments OPTION option; // out: option sheet sending the msg. 

U32 tag; // in: tag for tab 

WIN win; // in: card window or objNull 

P_CHAR pName; // in: card name 

U16 nameLen; // in: max. len for pName (for msgOptionGetCardAndName) 

OBJECT client; // in: for msgOptionRefreshCard, etc. 

U32 clientData[2] ; // in: arbitrary client data 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} OPTION_CARD, *P_OPTION_CARD; 

Comments This message is sent by the option sheet in response to msgOptionToggleDirty. 

The card's client should return stsOK if the card is dirty, stsRequestDenied if clean. 
Most clients do not need to deal with this message. 
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Message 
Arguments 



Comments 



OPTION option; 

U32 tag; 

WIN win; 

P_CHAR pNarae; 

U16 nameLen; 

OBJECT client; 

U32 clientData[2] 

U32 spare 1; 

U32 spare2; 



msgOptionApplyCard 

This is sent to a card's client when the card should apply its settings. 
Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 
#define msgOptionApplyCard MakeMsg(clsOption, 12) 

typedef struct OPTION_CARD { 

// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

With this message, an option option sheet tells a card to apply its settings to the selection. This is sent 
whenever the user chooses Apply or Apply &Close on the option sheet. 

Most clients need to override and handle this message. 

Here is the typical sequence of steps a card client should take in response: 

Run through every control in the card and for each one 1) check to see if it's dirty, and if it is 2) validate 
it if necessary. If any control has an invalid value, return stsFailed from the handler for 
msgOptionApplyCard. (This step can be omitted if there's no way any control could have an invalid 
value.) 

Again make a pass through every control in the card. If a control is dirty, apply its value. 

Finally, clean all the controls in the card. This can usually be done by sending 

msgControlSetDirty(false) to the card window. Note that most "command sheets" should have their 
control's CONTROL_STYLE.showDirty set false, and so this final step should be omitted. 



Arguments 



Comments 



msgOptionRefreshCard 

Tells a card's client to refresh its settings from the current selection. 
Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 
#define msgOptionRefreshCard MsgNoError(MakeMsg(clsOption, 11)) 
typedef struct OPTION CARD { 



OPTION option; 

U32 tag; 

WIN win; 

P_CHAR pName; 

U16 nameLen; 

OBJECT client; 

U32 clientData[2]; 

U32 sparel; 

U32 spare2; 



// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 



} OPTION_CARD, *P_OPTION_CARD; 

This is sent to a card's client when the option sheet has received msgOptionRefresh. The client should 
refresh the card's settings from the current selection. 

Most clients need to override and handle this message. 
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msgOptionApplicableCard 

Finds out if a card is applicable to the current selection. 

Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 

♦define msgOptionApplicableCard MakeMsg(clsOption, 22) 

Messoge typedef struct OPTION_CARD { 

Arguments OPTION option; // out: option sheet sending the msg. 

U32 tag; // in: tag for tab 

WIN win; // in: card window or objNull 

P_CHAR pName; // in: card name 

U16 nameLen; // in: max. len for pName (for msgOptionGetCardAndName) 

OBJECT client; // in: for msgOptionRefreshCard, etc. 

U32 clientData[2] ; // in: arbitrary client data 

U32 spare 1; // unused (reserved) 

U32 spare2; // unused (reserved) 

} OPTION_CARD, *P_OPTION_CARD; 

Comments The card's client should respond by returning stsOK if the card can be applied to the current selection, 

stsFailed if not. 

Most clients need to override and handle this message. 
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msgOptionDirtyCard 

Sent to a card's client when the card should dirty all its controls. 

Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 

♦define msgOptionDirtyCard MakeMsg(clsOption, 23) 

typedef struct OPTION_CARD { 
Arguments OPTION option; // out: option sheet sending the msg. 

// in: tag for tab 
// in: card window or objNull 
// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 
// in: for msgOptionRefreshCard, etc. 
// in: arbitrary client data 
// unused (reserved) 
// unused (reserved) 
} OPTION_CARD, *P_OPTION_CARD; 

Comments This is sent when the user changes the selection while an option sheet is up. It is needed so that if the 

card is applied to the new selection, every property on the card is applied, not just those changed by the 
user since the last apply. 

The usual scenario is for the card window to inherit from clsBorder, whose instances respond to 
msgBorderSetDirty by forwarding that message on to their immediate children. Card clients may elect 
NOT to respond to msgOptionDirtyCard~if the option sheet code gets back stsNotUnderstood, then 
it will send msgBorderSetDirty(true) to the card window. 

Most clients do not need to deal with this message. 

msgOptionCleanCard 

Sent to a card's client when the card should clean all its controls. 

Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 

♦define msgOptionCleanCard MakeMsg(clsOption, 36) 



Message 
Arguments 



Comments 



typedef struct OPTION_CARD { 
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} OPTION_CARD, *P_OPTION_CARD; 

This is sent after msgOptionApplyCard is sent. 

The usual scenario is for the card window to inherit from clsBorder, whose instances respond to 
msgBorderSetDirty by forwarding that message on to their immediate children. Card clients may elect 
to NOT respond to msgOptionCleanCard--if the option sheet code gets back stsNotUnderstood, then 
it will send msgBorderSetDirty(false) to the card window. 

Most clients do not need to deal with this message. 



Message 
Argument's 



Comments 



See Also 



msgOptionUpdateCard 

Sent to a card s client every time the card is about to be shown. 

Takes P_OPTION_CARD, returns STATUS. Category: client responsibility. 

♦define msgOptionUpdateCard MsgNoError(MakeMsg(clsOption, 24)) 



typedef struct OPTION_CARD 
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// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 



} OPTION CARD, *P OPTION CARD; 



Most clients do not need to respond to this message. It is intended for those circumstances where one 
card has dependencies on the state of another, and would need to look at that other card before being 
(re)displayed to the user. 

msgOptionRetireCard 



Messoge 
Arguments 



msgOptionRetireCard 

Sent to a card's client every time the current shown card is hidden. 
Takes P_OPTION_CARD, returns STATUS. Category: client responsibility, 
♦define msgOptionRetireCard MsgNoError(MakeMsg(clsOption, 43)) 



typedef struct OPTION CARD { 



OPTION 


option; 


U32 


tag; 


WIN 


win; 


P CHAR 


pName; 


U16 


nameLen; 


OBJECT 


client; 


U32 


clientData[2] 


U32 


sparel; 


U32 


spare2; 



// out: option sheet sending the msg. 

// in: tag for tab 

// in: card window or objNull 

// in: card name 

// in: max. len for pName (for msgOptionGetCardAndName) 

// in: for msgOptionRefreshCard, etc. 

// in: arbitrary client data 

// unused (reserved) 

// unused (reserved) 



} OPTION CARD, *P OPTION CARD; 
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Comments Most clients do not need to respond to this message. It is intended for those circumstances where one 

card builds a context (e.g., allocates resources) when shown, and needs to destroy the context when the 
card is no longer shown. This can happen when another card is turned to or when the option sheet is 
extracted or destroyed. 

See Also msgOptionUpdateCard 

Messages Option Sheets send to their 
frame's client 

msgOptionClosed 

This is sent to an option sheet's client when the sheet is closed. 

Takes OPTION, returns STATUS. Category: client responsibility. 

#define msgOptionClosed MakeMsg(clsOption, 13) 

Comments The client should respond by using msgAppRemoveFloatingWin to take down the option sheet, then 

optionally destroying the sheet with msgDestroy. 

Messages sheet clients should self -send 

msgOptionCreateSheet 

A message sent by convention by clients creating option sheets. 

Takes P_OPTION_TAG, returns STATUS. Category: descendant responsibility. 

fdefine msgOptionCreateSheet MakeMsg(clsOption, 16) 

Message typedef struct OPTION_TAG { 

Arguments OPTION option; 

TAG tag; 

} OPTIONJTAG, *P_OPTION_TAG; 

Comments When you need to create an option sheet, you should self-send this this message, rather than directly 

creating a sheet. By following this convention, subclasses can modify the sheet or supply a different one 
(which would have to behave the same as the original). 

When self-sending this message, the client should fill in the 'tag' of the option sheet desired (if 
applicable) or some other identifying value (some clients may create different kinds of option sheets). 
The client should also zero out the 'option' field of the OPTIONJTAG struct. 

In msgOptionCreateSheet, a client creates an EMPTY option sheet and fills in the 'option' field with 
the uid of the sheet. Subclasses handle this message by calling the ancestor's handler and then either 
modifying the sheet or supplying a new one (and destroying any non- null sheet already in the 'option' 
field). 

msgOptionAddCards 

A message to be sent by convention by clients creating option sheets. 
Takes P_OPTION_TAG, returns STATUS. Category: descendant responsibility, 
fdefine msgOptionAddCards MakeMsg(clsOption, 15) 
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Messages from other classes 

Message typedef struct OPTION_TAG { 

Arguments OPTION option; 

TAG tag; 

} OPTION_TAG, *P_OPTION_TAG; 

Comments This message embodies the second step of creating an option sheet. Just like msgOptionCreateSheet, 

msgOptionAddCards is self-sent by a client to fill in a sheet with some cards, and to allow subclasses of 
the client to modify cards or add different ones. 

if style.getCards is true, the option sheet sends this message to the frame's client as follows: 

- when the sheet is first inserted into the window tree 

- if style. cardNav is osNavPopup, when the card navigation menu is neededafter the selection has § 
changed. 

|F" Messages from other classes 

msgContentsButtonGoto 

Default message sent when the user taps on a menu button. 

Takes TAG, returns STATUS. Category: client notification. 

Comments This is also sent to the client when the managed button is hit. 

The option sheet responds by self-sending msgOptionShowCard with the following OPTION_CARD 
parameter: 

tag = pArgs; 

msgOptionBookProvideContents 

Receiver passes back a window representing its contents. 

Takes P_WIN, returns STATUS. 

Comments The option sheet responds by creating an instance of clsContentsTable with one clsContentsButton 

child for each card in the option sheet. Cards which themselves respond to 
msgOptionBookProvideContents are represented by cbSection style contents buttons. 
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OPTTABLE.H 



This file contains the API definition for clsOptionTable. 

clsOptionTable inherits from clsTkTable. 

Option tables implement no new behavior; they only change ancestor defaults to lay out their child 
windows in the standard two-column table format used by option sheets. 



tifndef OPTTABLE_INCLUDED 
tdefine OPTTABLE_INCLUDED 

tinclude <tktable.h> 



tifndef TKTABLE_INCLUDED 
#endif 



Common #defines and typedefs 

typedef OBJECT OPTION_TABLE; 

typedef struct OPTION_TABLE_STYLE { 

U16 spare : 16; // unused (reserved) 
} OPTION_TABLE_STYLE, *P_OPTION_TABLE_STYLE; 

ram 
Messages 



msgNew 

Creates an option table window. 

Takes P_OPTION_TABLE_NEW, returns STATUS. Category: class message. 

Arguments typedef struct OPTION_TABLE_NEW_ONLY { 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} OPTION_TABLE_NEW_ONLY, *P_OPTION_TABLE_NEW_ONLY; 

tdefine optionTableNewFields \ 
tkTableNewFields \ 

OPTION_TABLE_NEW_ONLY opt ionTable ; 

typedef struct OPTION_TABLE_NEW { 
optionTableNewFields 

} OPTION TABLE NEW, *P OPTION TABLE NEW; 



nesscsge 
Arguments 



msgNewDefaults 

Initializes the OPTION_TABLE_NEW structure to default values. 

Takes P_OPTION_TABLE_NEW, returns STATUS. Category: class message. 

typedef struct OPTION_TABLE_NEW { 

optionTableNewFields 
} OPTION TABLE NEW, *P OPTION TABLE NEW; 
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merits Sets 



pArgs->win. flags. style &= ~ (wsClipChildren | wsFilelnline) ; 
pArgs->border.style.leftMargin = bsMarginLarge; 
pArgs->border. style. rightMargin = bsMarginLarge; 
pArgs->border.style.bottomMargin = bsMarginLarge; 
pArgs ->border .style . t opMargin = bsMarginLarge ; 
pArgs->gWin.style.grabDown = false; 

pArgs->tableLayout. style. childXAlignment = tlAlignBaseline; 
pArgs->tableLayout . style . childYAlignment = tlAlignBaseline; 
pArgs->tableLayout . style . growChildWidth = false; 
pArgs->tableLayout . style . growChildHeight = false; 
pArgs->tableLayout.numRows. constraint = tllrifinite; 
pArgs->tableLayout.numRows. value = 0; 
pArgs->tableLayout .numCols. constraint = tlAbsolute; 
pArgs->tableLayout.numCols. value = 2; 

pArgs->tableLayout.colWidth. constraint = tlGroupMax | tlBaselineBox; 
pArgs->tableLayout.rowHeight. constraint = tlGroupMax | tlBaselineBox; 
pArgs->tableLayout.rowHeight.gap = de fault RowGap ; 
pArgs->tableLayout . colWidth . gap = defaultColGap; 

Sends msgNewDefaults to clsLabel to initialize pNew->tkTable.pButtonNew, then sets: 

pArgs->tkTable.pButtonNew->win. flags. style |= wsParentClip; 

pArgs->tkTable.pButtonNew->win. flags. style &= ~ (wsClipSiblings | wsClipChildren); 
pArgs->tkTable .pButtonNew->border. style .backgroundlnk = bsInkTransparent; 
pArgs->tkTable . pButt onNew->label . style . font Type = IsFontCustom; 
pArgs->tkTable .pButtonNew->label . font .attr. weight = sysDcWeightBold; 
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PAGENUM.H 



This file contains the API definition for clsPageNum. 

clsPageNum inherits from clsLabel. 

Page numbers are the standard notebook frame decorations which display the current page number. 



tifndef PAGENUM_INCLUDED 
♦define PAGENUM_INCLUDED 

♦include <label.h> 



tifndef LABEL_INCLUDED 
tendif 



F Common #defines and typedef s 



typedef OBJECT PAGE_NUM; 
typedef struct PAGE_NUM_STYLE { 

U16 spare : 16; // unused (reserved) 
} PAGE NUM STYLE, *P PAGE NUM STYLE; 



Messages 



msgNew 

Creates a pagenum window. 

Takes P_PAGE_NUM_NEW, returns STATUS. Category: class message. 

Arguments typedef struct PAGE_NUM_NEW_ONLY { 
PAGE_NUM_STYLE style; 

U32 pageNumber; // initial page number 

U32 spare; // unused (reserved) 

} PAGE_NUM_NEW_ONLY, *P_PAGE_NUM_NEW_ONLY; 

tdefine pageNumNewFields \ 

labelNewFields \ 

PAGE_NUM_NEW_ONLY pageNum; 
typedef struct PAGE_NUM_NEW { 

pageNumNewFields 
} PAGE NUM NEW, *P PAGE NUM NEW; 



nesscsge 
Arguments 



Comments 



msgNewDefaults 

Initializes the PAGE_NUM_NEW structure to default values. 

Takes P_PAGE_NUM_NEW, returns STATUS. Category: class message. 

typedef struct PAGE_NUM_NEW { 

pageNumNewFields 
} PAGE_NUM_NEW, *P_PAGE_NUM_NEW; 

Zeroes out pArgs->pageNum and sets 

pArgs->border. style. leftMargin = bsMarginMedium; 
pArgs->border. style. rightMargin = bsMarginMedium; 
pArgs->border.style.bottomMargin = bsMarginSmall; 
pArgs->border. style. topMargin = bsMarginMedium; 



316 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



pArgs->label . style. xAlignment = IsAlignRight; 
pArgs->label. style. yAlignment = IsAlignCenter; 



msgPageNumGetStyle 

Passes back the current style values. 

Takes P_PAGE_NUM_STYLE, returns STATUS. 

♦define msgPageNumGetStyle MakeMsg(clsPageNum, 1) 

Message typedef Struct PAGE_NUM_STYLE { 

Arguments U16 spare : 16; // unused (reserved) 

} PAGE NUM STYLE, *P PAGE NUM STYLE; 



msgPageNumSetStyle 

Sets the style values. 

Takes P_PAGE_NUM_STYLE, returns STATUS. 

♦define msgPageNumSetStyle MakeMsg(clsPageNum, 2) 

Me$$0ge typedef struct PAGE_NUM_STYLE { 

Arguments U16 spare : 16; // unused (reserved) 

) PAGE NUM STYLE, *P PAGE NUM STYLE; 



msgPageNumGet 

Passes back the current page number. 

Takes P_U32, returns STATUS. 

♦define msgPageNumGet MakeMsg(clsPageNum, 3) 



msgPageNumSet 

Sets the current page number. 

Takes U32, returns STATUS. 

♦define msgPageNumSet MakeMsg(clsPageNum, 4) 



msgPageNumlncr 

Increments the current page number. 

Takes S32, returns STATUS. 

♦define msgPageNumlncr MakeMsg(clsPageNum, 5) 
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POPUPCH.H 



This file contains the API for clsPopupChoice. 
clsPopupChoice inherits from clsMenuButton. 

Popup choices are buttons that pop up a menu of choices when tapped. 

A popup choice assumes that the first (bottom) child of its menu inherits from clsChoice. When this 
choice changes value, the popup choice button will copy the string of the new 'on' button in the choice 
as the popup choice's own string. Popup choices also respond to flick gestures by cycling their value 
among the set of possible values in the choice. 

^ Debugging Flags 

The clsPopupChoice debugging flag is 'K'. Defined values are: 
flag 13 (0x2000) general 



#ifndef POPUPCH_INCLUDED 
♦define POPUPCH_INCLUDED 

linclude <choice.h> 



tinclude <mbutton.h> 



tifndef CHOICE_INCLUDED 

tendif 

tifndef MBUTTON_INCLUDED 

#endif 



Common #defines and typedefs 

typedef struct POPUP_CHOICE_STYLE { 

U16 spare; 
} POPUP_CHOICE_STYLE, *P_POPUP_CHOICE_STYLE; 

typedef OBJECT POPUP CHOICE, *P POPUP CHOICE; 



msgNew 

Creates a popup choice button. 

Takes P_POPUP_CHOICE_NEW, returns STATUS. Category: class message. 

Arguments typedef struct P0PUP_CH0ICE_NEW_0NLY { 

POPUP_CHOICE_STYLE style; 

U32 spare; // unused (reserved) 

} P0PUP_CH0ICE_NEW_0NLY, *P_POPUP_CHOICE_NEW_ONLY; 

fdefine popupChoiceNewFields \ 
menuButtonNewFields \ 

P0PUP_CH0ICE_NEW_0NLY popupChoice ; 

typedef struct POPUP_CHOICE_NEW { 

popupCho i ceNewF i e Ids 
} POPUP_CHOICE_NEW, *P_POPUP_CHOICE_NEW; 

Comments The popup choice will set its pString from the 'on' button within the popup's choice, if any button there 

is 'on'. 
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The fields you commonly set are: 

pArgs->menuButton.menu uid of a menu whose first child is a choice 



msgNewDefaults 

Initializes the POPUP_CHOICE_NEW structure to default values. 

Takes P_POPUP_CHOICE_NEW, returns STATUS. Category: class message. 

Message typedef struct POPUP_CHOICE_NEW { 

Arguments popupChoiceNewFields 

} POPUP_CHOICE_NEW, *P_POPUP_CHOICE_NEW; 

Comments Zeroes out pArgs->popupChoice and sets: 

pArgs->gWin. style. gestureEnable = true; 
pArgs->control. style. showDirty = true; 
pArgs->label . style . decoration = lsDecorationPopup; 
pArgs->button. style. feedback = bsFeedbackNone; 
pArgs ->menuBut ton. style. subMenuType = mbMenuPopup; 
pArgs->menuButton. style. getWidth = true; 



msgPopupChoiceGetStyle 

Passes back the receiver's style. NOT IMPLEMENTED. 

Takes P_POPUP_CHOICE_STYLE, returns STATUS. 

fdefine msgPopupChoiceGetStyle 

typedef struct POPUP_CHOICE_STYLE { 

U16 spare; 
} POPUP CHOICE STYLE, *P POPUP CHOICE STYLE; 



msgPopupChoiceSetStyle 

Sets the receiver's style. NOT IMPLEMENTED. 

Takes P_POPUP_CHOICE_STYLE, returns STATUS. 

tdefine msgPopupChoiceSetStyle MakeMsg(clsPopupChoice, 2) 

Message typedef struct POPUP_CHOICE_STYLE { 

Arguments U16 spare; 

} POPUP CHOICE STYLE, *P POPUP CHOICE STYLE; 



msgPopupChoiceGetChoice 

Passes back the choice associated with this popup. 

Takes P_CHOICE, returns STATUS. 

#define msgPopupChoiceGetChoice MakeMsg(clsPopupChoice, 3) 

The popup choice will self-send msgMenuButtonGetMenu to get the menu. If the menu is null, the 
popup choice will set *pArgs null and return stsOK. Otherwise, *pArgs will be set to the first child of 
the menu. 
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Messages from Other Classes 



^Messages from Other Classes 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes P_WIN_SEND, returns STATUS. 

Comments If pArgs->msg is not msgMenuDone, clsPopupChoice just calls its ancestor. 

Otherwise, clsPopupChoice calls its ancestor (to allow clsMenuButton to take down the menu), then 
resets its visuals to reflect the new 'on' button within the choice. 

For popup choices that display a string, this just means obtaining the string from the 'on' button (or, if 
the button has LABEL_STYLE.infoType of lsInfoWindow, from the first lsInfoString label found within 
using depth enumeration) and using msgLabelSetString on self. 

For popup choices that display an icon, the visuals are changed by getting the icon within self 
(msgLabelGetWin), sending it msglconFreeCache, setting its window tag to the tag of the 'on' icon, 
and finally using msgWinDirtyRect(pNull) to get the icon to repaint. Note that because of this strategy, 
the icon within self cannot change size when its picture changes. The picture size is not copied from the 
'on' icon to the icon within self. 

msgGWinGesture 

Self-sent to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

Comments If the popup 's CONTROL_STYLE. enable is false, the popup choice just returns stsOK. 

If the class of pArgs->msg is not clsXGesture, the popup choice returns stsMessagelgnored. 

If pArgs->msg is not one of xgsFlick* or xgsDblFlick*, then the popup choice returns the result of 
calling its ancestor. 

Otherwise, the popup choice obtains the 'on button within its choice, and searches through the choice's 
list of children for the next, previous, first, or last child based on what type of flick gesture was received. 
The popup choice sets its value to be this new button and returns stsOK. Buttons that are not enabled 
(msgControlGetEnable) are skipped over. 

Return ¥alue stsMessagelgnored pArgs->msg is not of clsXGesture. 

msgControlGetValue 

Passes back the receiver's value (tag of button that is on). 

Takes P_TAG, returns STATUS. 

Comments clsPopupChoice overrides clsButton's response (of passing back BUTTON_STYLE.on) by instead 

forwarding msgControlGetValue on to its choice. This means popup choices behave like choices with 
respect to msgControlGetValue. 
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msgControlSetValue 

Sets the receiver's value. 

Takes TAG, returns STATUS. 

Comments clsPopupChoice overrides clsButton's response (of setting BUTTON_STYLE.on) by instead forwarding 

msgControlSetValue on to its choice. Changing the choice's value then results in an update of the 
popup's label string. This means popup choices behave like choices with respect to msgControlSetValue. 

msgControlGetClient 

Passes back the receiver's client. 
Takes P_UID, returns STATUS. 
Comments clsPopupChoice intercepts this message and forwards it on to the popup's choice. 



msgControlSetClient 

clsPopupChoice forwards this message on to the popup's choice. 
Takes UID, returns STATUS. 



msgControlBeginPreview 

clsPopupChoice responds by noting internally that its menu is now up, then calling ancestor. 
Takes P_INPUT_EVENT, returns STATUS. 



Comments 



msgControlSetMetrics 

Sets the metrics. 

Takes P_CONTROL_METPJCS, returns STATUS. 

If the popup choice's menu is up, it prohibits the CONTROL_STYLE.dirty bit from changing. 



Comments 



msgControlSetStyle 

Sets the style values. 

Takes P_CONTROL_STYLE, returns STATUS. 

If the popup choice's menu is up, it prohibits the CONTROL_STYLE.dirty bit from changing. 



msgControlSetDirty 

Sets style.dirty. 

Takes BOOLEAN, returns STATUS. 
Comments If the popup choice's menu is up, it prohibits the CONTROL_STYLE.dirty bit from changing 



msgMenuButtonProvideWidth 

Self-sent when MENU_BUTTON_STYLE.getWidth is true. 

Takes P_S32, returns STATUS. Category: self-sent. 

clsPopupChoice responds by computing a width based on its menu. 
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Messages from Other Classes 

If the wsLayoutDirty bit of its menu is true, the popup choice will lay out its menu. clsPopupChoice 
then enumerates all the children of its choice and computes the maximum width of all the children that 
inherit from clsLabel and whose LABEL_STYLE.infoType is not lsInfoWindow (if an IsInfoWindow 
label child is encountered, clsPopupChoice will find the first string-type label within it and use the 
width of that). 

msgMenuButtonPlaceMenu 

Self-sent whenever a menu button needs to position its associated menu. 

Takes P_WIN_METRICS, returns STATUS. Category: self-sent. 

Comments clsPopupChoice first gets the 'on' button from its choice. If there is a button on, clsPopupChoice will 

position its menu so that the 'on' button is adjacent to the popup. If there is no button on in the choice, 
clsPopupChoice just calls its ancestor. 
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PROGRESS.H 



This file contains the API for clsProgressBar. 
clsProgressBar inherits from clsControl. 

Implements a read-only or read/write progress indicator. 

Debugging Flags 

The clsProgressBar debugging flag is 'K\ Defined values are: 
flagl 4 (0x4000) general 



♦ifndef PROGRESS_INCLUDED 
♦define PROGRESS_INCLUDED 

♦include <control.h> 
♦include <sysgraf.h> 



#ifndef CONTROL_INCLUDED 

♦endif 

tifndef SYSGRAF_INCLUDED 

tendif 



Common #defines and typedels 



// Labels style 
♦define psLabelsNumeric 
♦define psLabelsNone 
♦define psLabelsCustom 

// Ticks style 
♦define psTicksSmall 
♦define psTicksFull 
♦define psTicksNone 

// Direction style 

♦define psDirectionHorizontal 

♦define psDirectionVertical 

// Thickness style 
♦define psThicknessRelFont 
♦define psThicknessFixed 

// Edge Styles 
♦define psEdgeNone 
♦define psEdgeMinLat 
♦define psEdgeMaxLat 
♦define psEdgeMinLong 
♦define psEdgeMaxLong 
♦define psEdgeAll 



// horizontal indicator 
// vertical indicator 

// thickness varies with system font size 
// thickness is fixed 





flagO 

flagl 

flag2 

flag3 

(psEdgeMinLat 

psEdgeMinLong 



psEdgeMaxLat I \ 
psEdgeMaxLong) 
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"Lat" is latitude, and "Long" is longitude. For horizontal progress bars, latitude is the y dimension (or 
minor axis), and longitude is the x dimension (or major axis). For vertical bars, lat is x, and long is y. 



typedef struct PROGRESS_STYLE { 



U16 labels 

ticks 

direction 

units 

thickness 

labelRotation 
U16 labelScaleUnits 

edge 

labelFontType 
spare 
U16 spare2 



2, 
2, 
2, 
6, 
2, 
2; 



// labels style 

// style of ticks to paint 

// direction of major axis 

// units for everything except labels 

// thickness style for lines and ticks 

// use IsRotate* from label. h 

// scale units for labels from border. h 



4, // bar edges to display 



2, 
4; 

16; 
} PROGRESS_STYLE, *P_PROGRESS 

Default PROGRESS STYLE: 



// (separate from clsBorder edges) 
// use IsFont* from label. h 
// unused (reserved) 
// unused (reserved) 
STYLE; 



labels 

ticks 

direction 

units 

thickness 

labelRotation 

labelFontType 



= psLabelsNone 

= psTicksNone 

= psDirectionHorizontal 

= bsUnitsPoints 

= psThicknessRelFont 

= IsRotateNone 

= IsFontSystem 



labelScaleUnits = bsUnitsLayout 



edge 



= psEdgeMinLat | psEdgeMinLong 



typedef struct PROGRESS_REGION { 

U32 rgb; 

SYSDC_PATTERN pattern; 
} PROGRESS_REGION, *P_PROGRESS_REGION; 

typedef struct PROGRESS_METRICS { 



PROGRESS_STYLE 
S32 
S32 
S32 
S32 
U16 
U16 
U16 
S32 
S32 

SYSDC_FONT_SPEC 
U8 
U32 
U32 
PROGRESS METRICS, 



style; 

numlntervals; 

ticksPerLabel; 

minNumericLabel ; 

maxNumericLabel ; 

thicknessBase; 

latitude; 

longitude; 

maxValue; 

value; 



// overall style 



// gives period of labels 

// when psLabelsNumeric 

// when psLabelsNumeric 

// thickness (units or multiplier) 

// dimension of minor axis (in units) 

// dimension of major axis (in units) 

// values are in [0. .maxValue] 

// current value 

font; // spec to open if style . labelFontType == IsFontCustom 

labelScale; // scale for labels as in border. h 

sparel; // unused (reserved) 

spare2; // unused (reserved) 

*P PROGRESS METRICS; 



metrics.latitude and .longitude are used only when the progress bar is shrink-wrapped in those 
dimensions. "When not shrink-wrapped, the progress bar expands to fill the available space. 



Arguments 



msgNew 

Creates a progress indicator. 

Takes P_PROGRESS_NEW, returns STATUS. Category: class message. 



typedef struct PROGRESS_NEW_ONLY { 
PROGRESS_METRICS metrics; 
P_CHAR fontName; 

U32 sparel; 

U32 spare2; 



// font name from which to derive font. id 
// unused (reserved) 
// unused (reserved) 



} PROGRESS NEW ONLY, *P PROGRESS NEW ONLY; 
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Common #defines and typedefs 
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♦define progressNewFields \ 
controlNewFields \ 
PROGRESS_NEW_ONLY progres s ; 

typedef struct PROGRESS_NEW { 

progressNewFields 
} PROGRESS_NEW, *P_PROGRESS_NEW; 

Comments The filled region looks are initialized with: 

rgb = SysDcGrayRGB(128) 

pattern = sysDcPatForeground 

The unfilled region looks are initialized with: 

rgb = sysDcRGBTransparent 

pattern = sysDcPatNil 



Message 
Arguments 



Comments 



msgNewDefaults 

Initializes the PROGRESS_NEW structure to default values. 

Takes P_PROGRESS_NEW, returns STATUS. Category: class message. 

typedef struct PROGRESS_NEW { 

progressNewFields 
} PROGRESS_NEW, *P_PROGRESS_NEW; 

Zeroes out pArgs->progress and sets: 

pArgs->win. flags. style |= wsShrinkWrapWidth | wsShrinkWrapHeight; 

pArgs->border.style.previewAlter = bsAlterNone; 
pArgs->border.style.selectedAlter = bsAlterNone; 

pArgs->control . style . showDirty = false; 

pArgs->progress. metrics. style. labels = p s Label sNone ; 
pArgs->progress. metrics. style. ticks = psTicksNone; 
pArgs->progress. metrics. style. units = bsUnitsPoints; 
pArgs->progress. metrics. style. labelScaleUnits = bsUnitsLayout; 
pArgs->progress. metrics. style. edge = psEdgeAll; 
pArgs->progress. metrics. numlntervals = 10; 
pArgs->progress. metrics. ticksPerLabel = 2; 
pArgs->progress. metrics. minNumericLabel = 0; 
pArgs->progress. metrics. maxNumericLabel = 100; 
pArgs->progress. metrics. thicknessBase = 1; 
pArgs->progress. metrics. latitude = 18; 
pArgs->progress. metrics. longitude = 144; 
pArgs->progress. metrics. maxValue = 100; 
pArgs->progress. metrics. value = 0; 
pArgs->progress. metrics. labelScale = IsScaleMedium; 

Also sets pArgs->progress. metrics, font to the default system font. 

msgProgressGetStyle 

Passes back the current style. 

Takes P_PROGRESS_STYLE, returns STATUS. 

♦define msgProgressGetStyle MakeMsg(clsProgressBar, 1) 
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typedef struct PROGRESS STYLE { 



U16 labels 

ticks 

direction 

units 

thickness 

labelRotation 
U16 labelScaleUnits 

edge 

labelFontType 
spare 
U16 spare2 



2, 
2, 
2, 
6, 
2, 
2; 
6, 
4, 

2, 
4; 

16; 



7/ labels style 

// style of ticks to paint 

// direction of major axis 

// units for everything except labels 

// thickness style for lines and ticks 

// use IsRotate* from label. h 

// scale units for labels from border. h 

// bar edges to display 

// (separate from clsBorder edges) 

// use IsFont* from label. h 

// unused (reserved) 

// unused (reserved) 



} PROGRESS STYLE, *P PROGRESS STYLE; 



Message 
Arqymeni 



Comments 



msgProgressSetStyle 

Sets the style. 

Takes P_PROGRESS_STYLE, returns STATUS. 

#define msgProgressSetStyle MakeMsg(clsProgressBar, 2) 



typedef struct PROGRESS STYLE { 



U16 labels 

ticks 

direction 

units 

thickness 

labelRotation 
U16 labelScaleUnits 

edge 

labelFontType 
spare 
U16 spare2 



2, 
2, 
2, 
6, 
2, 
2; 
6.- 
A, 

2, 

4; 
16; 



// labels style 

// style of ticks to paint 

// direction of major axis 

// units for everything except labels 

// thickness style for lines and ticks 

// use IsRotate* from label. h 

// scale units for labels from border. h 

// bar edges to display 



// 
// 



(separate from clsBorder edges) 
use IsFont* from label. h 



// unused 
// unused 



(reserved) 
(reserved) 



} PROGRESS_STYLE, *P_PROGRESS_STYLE; 

The progress bar will set its layout bit dirty (as in msgWinSetLayoutDirty) as necessary. It will use 
msgWinDirtyRect in a similar fashion. It is the client's responsibility to send msgWinLayout to the 
progress bar whenever the style changes would affect the layout. 



Messoge 
Arguments 



msgProgressGetMetrics 

Passes back the current metrics. 

Takes P_PROGRESS_METRICS, returns STATUS. 

♦define msgProgressGetMetrics MakeMsg(clsProgressBar, 3) 



typedef struct PROGRESS_METRICS { 

PROGRESS_STYLE style; 

S32 

S32 

S32 

S32 

U16 

U16 

U16 

S32 

S32 

SYSDC_FONT_SPEC 

U8 

U32 

U32 
} PROGRESS METRICS, 



numlntervals; 
ticksPerLabel; 
minNumericLabel ; 
maxNume r i cLabe 1 ; 
thicknessBase; 
latitude; 
longitude ; 
maxValue; 
value; 



// overall style 

// gives period of labels 

// when psLabelsNumeric 

// when psLabelsNumeric 

// 

// 

// 

II 

II 



thickness (units or multiplier) 
dimension of minor axis (in units) 
dimension of major axis (in units) 
values are in [0. .maxValue] 
current value 

font; // spec to open if style . labelFontType == IsFontCustom 

labelScale; // scale for labels as in border. h 

sparel; // unused (reserved) 

spare2; // unused (reserved) 

*P PROGRESS METRICS; 
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msgProgressSetMetrics 

Sets the metrics. 

Takes P_PROGRESS_METRICS, returns STATUS. 

#define msgProgressSetMetrics MakeMsg(clsProgressBar, 4) 

message typedef struct PROGRESS_METRICS { 

Arguments PROGRESS_STYLE Style; // overall Style 

S32 numlntervals; 

S32 ticksPerLabel; // gives period of labels 

S32 minNumericLabel; // when psLabelsNumeric 

S32 maxNumericLabel; // when psLabelsNumeric O 

U16 thicknessBase; // thickness (units or multiplier) 

U16 latitude; // dimension of minor axis (in units) 

U16 longitude; // dimension of major axis (in units) 

S32 maxValue; // values are in [0. .maxValue] 

S32 value; // current value 

SYSDC_FONT_SPEC font; // spec to open if style . labelFontType == IsFontCustom 

U8 labelScale; // scale for labels as in border. h 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} PROGRESS_METRICS, *P_PROGRESS_METRICS; 

Comments The progress bar will set its layout bit dirty (as in msgWinSetLayoutDirty) as necessary. It will use 

msgWinDirtyRect in a similar fashion. It is the client's responsibility to send msgWinLayout to the 
progress bar whenever the changes would affect the layout. 

msgProgressGetFilled 

Passes back the current filled region looks. 

Takes P_PROGRESS_REGION, returns STATUS. 

#define msgProgressGetFilled MakeMsg(clsProgressBar, 5) 

Message typedef Struct PROGRESS_REGION { 

Arguments U32 rgb; 

SYSDC_PATTERN pattern; 
} PROGRESS_REGION, *P_PROGRESS_REGION; 

msgProgressSetFilled 

Sets the current filled region looks. 

Takes P_PROGRESS_REGION, returns STATUS. 

♦define msgProgressSetFilled MakeMsg(clsProgressBar, 6) 

Message typedef struct PROGRESS_REGION { 

Arguments U32 rgb; 

SYSDC_PATTERN pattern; 
} PROGRESS_REGION, *P_PROGRESS_REGION; 

Comments The progress bar will self-send msgWinDirtyRect as necessary. 

msgProgressGetUnfilled 

Passes back the current unfilled region looks. 

Takes P_PROGRESS_REGION, returns STATUS. 

tdefine msgProgressGetUnfilled MakeMsg(clsProgressBar, 7) 
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■sssage typedef struct PROGRESS_REGION { 

gsumertfs U32 rgb; 

SYSDC_PATTERN pattern; 
} PROGRESS REGION, *P PROGRESS REGION; 



msgProgressSetUnfilled 

Sets the current unfilled region looks. 

Takes P_PROGRESS_REGION, returns STATUS. 

♦define msgProgressSetUnfilled MakeMsg(clsProgressBar, 8) 

typedef struct PROGRESS_REGION { 

U32 rgb; 

SYSDC_PATTERN pattern; 
} PROGRESS_REGION, *P_PROGRESS_REGION; 

The progress bar will self-send msgWinDirtyRect as necessary. 



msgProgressProvideLabel 

Sent to the client when style.labels == psLabelsCustom. 

Takes P_PROGRESS_PROVIDE_LABEL, returns STATUS. Category: client responsibility. 

#define msgProgressProvideLabel MakeMsg(clsProgressBar, 9) 

Arguments typedef Struct PROGRESS_PROVIDE_LABEL { 

CONTROL progressBar; // In: requestor 

U16 position; // In: position of label (0 at minimum) 

P_CHAR pString; // Out: a 256 byte buffer for the string 

U32 spare; // unused (reserved) 

} PROGRESS_PROVIDE_LABEL, *P_PROGRESS_PROVIDE_LABEL; 

Comments The client should copy a string for the indicated position into the provided buffer. 



msgProgressGetVisInfo 

Passes back information about the current state of the visuals. 

Takes P_PROGRESS_VIS_INFO, returns STATUS. 

♦define msgProgressGetVisInfo MakeMsg(clsProgressBar, 10) 

ments typedef struct PROGRESS_VIS_INFO { 

RECT32 filledRect, 

unfilledRect; 
U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} PROGRESS_VIS_INFO, *P_PROGRESS_VIS_INFO; 

ments All measurements are in LWC (device units). 

Messages from Other Classes 



msgControlGetValue 

Passes back the receiver's value (metrics.value). 
Takes P_S32, returns STATUS. 
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msgControlSetValue 

Sets the receiver's value. 
Takes S32, returns STATUS. 
Comments The progress bar will self-send msgWinDirtyRect as necessary. 



.omments 



msgSave 

Causes an object to file itself in an object file. 



Takes P OBJ SAVE, returns STATUS. O 

- J - 

clsProgressBar responds by filing away all of its state. a 



msgRestore 

Creates and restores an object from an object file. 
Takes P_OBJ_RESTORE, returns STATUS. 
lomments clsLabel responds by restoring all of its state. 



msgWinLayoutSelf 

Tell a window to layout its children. 

Takes P_WIN_METRICS, returns STATUS. 

clsProgressBar responds by recomputing its layout parameters. 

If the receiver is shrink-wrapping in a dimension, it will use the latitude or longitude value as 
appropriate to determine the interior dimension of the progress bar (which does not include the inked 
edges of the bar). When not shrink-wrapping in a dimension, the corresponding latitude or longitude 
value is ignored. 



msgWinRepaint 

Tells a window to repaint itself. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

clsProgressBar responds by painting the edges, bar, ticks, and labels. 

First, the progressBar self-sends msgControlGetValue to get its current value and then 
msgBorderGetForegroundRGB to get the color in which to paint the edges, ticks, and labels. It then 
paints the edges. 

Next, the progressBar will paint the unfilled portion of the bar if the unfilled pattern isn't sysDcPatNil. 
The pattern will be painted with the specified foreground RGB and a background RGB obtained by 
self-sending msgBorderGetBackgroundRGB. See msgProgressSetUnfilled. 

The progressBar will then paint the filled portion of the bar if the filled pattern isn't sysDcPatNil. The 
method is as described above. See msgProgressSetFilled. 

While drawing the tick marks, the progressBar will self-send msgBorderRGBToInk and use a 
foreground color that is opposite so that the ticks will show up against the filled/unfilled regions. 

Finally, the labels are painted using a foreground RGB obtained by self-sending 
msgBorderGetForegroundRGB. 
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msgWinGetBaseline 

Gets the desired x,y alignment of a window. 

Takes P_WIN_METRICS, returns STATUS. 

clsProgressBar responds by setting pArgs->bounds.origin to the origin of the bar within self. 
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SBAR.H 



This file contains the API definition for clsScrollbar. 

clsScrollbar inherits from clsControl. 

Scrollbars provide scrolling visuals and define a protocol for handling various kinds of scrolling actions. 

Debugging Flags 

The clsScrollbar debugging flag is 'K'. Defined values are: 

flag2 (0x0004) protocol messages 

flag6 (0x0040) painting 

flaglO (0x0400) input 

flagl4 (0x4000) general debug info 



tifndef SBAR_INCLUDED 
#define SBAR_INCLUDED 

#include <control.h> 



#ifndef CONTROL_INCLUDED 
#endif 



Common #defines and typedefs 



#define hlpScrollbarVertical MakeTag (clsScrollbar, 1) 

#define hlpScrollbarHorizontal MakeTag (clsScrollbar, 2) 

tdefine hlpScrollbarGeneral hlpScrollbarVertical 
typedef OBJECT SCROLLBAR; 



Direction 



#define sbDirectionVertical 
#define sbDirectionHorizontal 1 
typedef struct SCROLLBAR_STYLE { 



//■ vertical scrollbar 
// horizontal scrollbar 



U16 direction 

wide 

spare 



1, 
1, 
14; 



//no longer implemented 
// unused (reserved) 



} SCROLLBAR_STYLE, *P_SCR0LLBAR_STYLE; 
Default SCROLLBAR_STYLE: 

direction = sbDirectionVertical 
Enuml6(SCR0LLBAR_ACTI0N) { 

// For vertical scrollbars: 



sbLineUp 


= o, 


sbLineDown 


= 1, 


sbPageUp 


= 2, 


sbPageDown 


= 3, 


sbThumbUpDown 


= 4, 


sbLineToTop 


= U, 


sbLineToBottom 


= 12, 


sbToTop 


= 15, 


sbToBottom 


= 16, 
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// For horizontal scrollbars: 



sbLineLeft 


= 5, 


sbLineRight 


= 6, 


sbPageLeft 


= 7, 


sbPageRight 


= 8, 


sbThumbLeftRight 


= 9, 


sbColumnToLeft 


= 13, 


sbColumnToRight 


= 14, 


sbToLeft 


= 17, 


sbToRight 


= 18, 


// Terminating action: 


sbEndScroll 

\ ■ 


= 10 


1 1 

typedef struct SCROLLBAR_SCROLL { 


SCROLLBAR 


sb; 


SCROLLBAR ACTION 


action; 


S32 


offset; 


S32 


lineCoord; 


U32 


spare 1; 


U32 


spare2 ; 



// in: originating scrollbar 
// in: current action 
// in/out: current or new offset 
// in: coordinate of line in root win space 
// unused (reserved) 
// unused (reserved) 
} SCROLLBAR_SCROLL, *P_SCROLLBAR_SCROLL; 

typedef struct SCROLLBAR_PROVIDE { 

SCROLLBAR sb; // in: originating scrollbar 

S32 viewLength; // out: client -provided view width or height 

S32 docLength; // out: client -provided document width or height 

S32 offset; // out: client -provided current offset 

U32 spare; // unused (reserved) 

} SCROLLBAR PROVIDE, *P SCROLLBAR PROVIDE; 



Messages 



msgNew 

Creates a scrollbar window. 

Takes P_SCROLLBAR_NEW, returns STATUS. Category: class message. 

typedef struct SCROLLBAR_NEW_ONLY { 
SCROLLBAR_STYLE style; 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} SCROLLBAR_NEW_ONLY, *P_SCROLLBAR_NEW_ONLY; 

#define scrollbarNewFields \ 
controlNewFields \ 

SCROLLBAR_NEW_ONLY scrollbar; 

typedef struct SCROLLBAR_NEW { 

scrollbarNewFields 
} SCROLLBAR_NEW, *P_SCROLLBAR_NEW; 

The fields you commonly set are: 
pArgs->scrollbar.style.direction whether horizontal or vertical 



msgNewDefaults 

Initializes the SCROLLBAR_NEW structure to default values. 

Takes P_SCROLLBAR_NEW, returns STATUS. Category: class message. 



tessoge typedef struct SCROLLBAR_NEW { 

Arguments scrollbarNewFields 

} SCROLLBAR NEW, *P SCROLLBAR NEW; 
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Comments Zeroes out pArgs->scrollbar and sets 

pArgs->win. flags. style |= wsShrinkWrapWidth | wsShrinkWrapHeight; 
pArgs->win. flags. input = inputTip; 

pArgs->gWin.helpId = hlpScrollbarVertical; 

pArgs->control. style. previewGrab - true; 
pArgs->control. style. previewRepeat = true; 
pArgs->control. style. previewEnable = true; 
pArgs->scrollbar. style. direction = sbDirectionVertical; 



Message 
Arguments 



Comments 



msgScrollbarGetStyle 

Passes back the current style values. 

Takes P_SCROLLBAR_STYLE, returns STATUS. 

♦define msgScrollbarGetStyle MakeMsg(clsScrollbar, 1) 

typedef struct SCROLLBAR STYLE { 



U16 direction 
wide 
spare 



1, 
1, 
14; 



//no longer implemented 
// unused (reserved) 



} SCROLLBAR_STYLE, *P_SCROLLBARSTYLE; 

msgScrollbarSetStyle 

Sets the style values. 

Takes P_SCROLLBAR_STYLE, returns STATUS. 

tdefine msgScrollbarSetStyle MakeMsg(clsScrollbar, 2) 

typedef struct SCROLLBAR_STYLE { 



U16 direction 
wide 
spare 



1, 
1, 
14; 



//no longer implemented 
// unused (reserved) 



} SCROLLBAR_STYLE, *P_SCROLLBAR STYLE; 

msgScrollbarUpdate 

Forces the scrollbar to repaint with the latest info. 

Takes nothing, returns STATUS. 

tdefine msgScrollbarUpdate MakeMsg(clsScrollbar, 14) 

Causes msgScrollbarProvideVert/HorizInfo to be sent to client. 



Self-Sent/Client Messages 

msgScrollbarVertScroll 

Client should perform vertical scroll. 

Takes P_SCROLLBAR_SCROLL, returns STATUS. Category: client responsibility. 

#define msgScrollbarVertScroll MakeMsg(clsScrollbar, 5) 



typedef struct SCROLLBAR SCROLL { 



SCROLLBAR 


sb; 


SCROLLBAR ACTION 


action; 


S32 


offset; 


S32 


lineCoord; 


U32 


spare 1; 


U32 


spare2 ; 



// in: originating scrollbar 

// in: current action 

// in/out: current or new offset 

// in: coordinate of line in root win space 

// unused (reserved) 

// unused (reserved) 



} SCROLLBAR SCROLL, *P SCROLLBAR SCROLL; 
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Comments 



The passed offset is an estimate computed by the scrollbar based on the information obtained from 
msgScrollbarProvideVertlnfo . 

If the client is unwilling to scroll to this offset, the client may scroll to a different offset. Be sure to set 
pArgs->offset to the new offset if it's different from the passed value. 



msgScrollbarHorizScroll 

Client should perform horizontal scroll. 

Takes P_SCROLLBAR_SCROLL, returns STATUS. Category: client responsibility. 

tdefine msgScrollbarHorizScroll MakeMsg(clsScrollbar, 6) 

typedef struct SCROLLBARJSCROLL { 

SCROLLBAR sb; // in: originating scrollbar 

SCROLLBAR_ACTION action; // in: current action 

S32 offset; // in/out: current or new offset 

S32 lineCoord; // in: coordinate of line in root win space 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} SCROLLBAR_SCROLL, *P_SCROLLBAR_SCROLL; 

The passed offset is an estimate computed by the scrollbar based on the information obtained from 
msgScrollbarProvideHorizInfo . 

If the client is unwilling to scroll to this offset, the client may scroll to a different offset. Be sure to set 
pArgs->offset to the new offset if it's different from the passed value. 

msgScrollbarProvideVertlnfo 

Client should provide the document and view info. 

Takes P_SCROLLBAR_PROVIDE, returns STATUS. Category: client responsibility. 

tdefine msgScrollbarProvideVertlnfo MakeMsg(clsScrollbar, 9) 

typedef struct SCROLLBAR_PROVIDE { 

SCROLLBAR sb; //in: originating scrollbar 

S32 viewLength; // out: client -provided view width or height 

S32 docLength; // out: client -provided document width or height 

S32 offset; // out: client -provided current offset 

U32 spare; // unused (reserved) 

} SCROLLBAR PROVIDE, *P SCROLLBAR PROVIDE; 



msgScrollbarProvideHorizInfo 

Client should provide the document and view info. 

Takes P_SCROLLBAR_PROVIDE, returns STATUS. Category: client responsibility. 

tdefine msgScrollbarProvideHorizInfo MakeMsg(clsScrollbar, 10) 

typedef struct SCROLLBAR_PROVIDE { 

SCROLLBAR sb; //in: originating scrollbar 

S32 viewLength; // out: client -provided view width or height 

S32 docLength; // out: client -provided document width or height 

S32 offset; // out: client -provided current offset 

U32 spare; // unused (reserved) 

} SCROLLBAR PROVIDE, *P SCROLLBAR PROVIDE; 
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Messages from Other Classes 



msgSave 

Causes an object to file itself in an object file. 
Takes P_OBJ_SAVE, returns STATUS. 
Comments clsScrollbar responds by filing away its instance data. 



msgRestore S 

Creates and restores an object from an object file. P- 

5 
Takes P_OBJ_RESTORE, returns STATUS. ^ 

Comments clsScrollbar responds by restoring its instance data. ■■ 



msgWinRepaint 

Tells a window to repaint itself. 

Takes nothing, returns STATUS. Category: descendant responsibility. 
ts clsScrollbar responds by painting itself appropriately. 

msgWinLayoutSelf 

Tell a window to layout its children. 

Takes P_WIN_METRICS, returns STATUS. 

ts clsScrollbar does nothing if pArgs->options does not have wsLayoutResize turned on. Otherwise, it will 

set pArgs->bounds.size only for the dimensions for which shrinkwrapping is set. It will set pArgs->size.w 
and h to a value derived from msgBorderlnsetToInnerRect and an internal constant (currently 1 3 
points). 

The visuals of the scrollbar are painted within the innerRect. 

See Also msgBorderlnsetToInnerRect insets arbitrary rect to border rect. 

msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments clsScrollbar responds to input events by maintaining the state necessary to behave in the appropriate 

fashion. The types of input state a scrollbar can be in are: 

null 

pen up over an arrow 

pen down over an arrow 

pen up over the thumb 

pen down over the thumb 

dragging the thumb 

pen up over the shaft 

gesturing over the shaft 
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In particular, the scrollbar allows the normal msgControl*Preview protocol to ensue only when the pen 
is interacting with the scroll arrows. 

msgGWinGesture 

Called to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

Comments clsScrollbar responds by returning stsMessagelgnored if the gesture has no meaning (e.g. xgsFlickUp on 

a horizontal scrollbar). 

Otherwise, the scrollbar will fill out a SCROLLBAR_SCROLL struct and send either 
msgScrollbarVertScroll or msgScrollbarHorizScroll to the CONTROL_METRICS. client. Actually, the 
client will receive the message twice—once for the appropriate action, and once for the sbEndScroll 
action (although the second message with sbEndScroll may be dropped in the future). 

msgGWinComplete 

Causes the gesture to be completed. 

Takes void, returns STATUS. 

Comments clsScrollbar responds by clearing its internal state data left over from processing a gesture in the scrollbar 

shaft. 

msgControlBeginPreview 

Self-sent when msgPenDown is received. 

Takes P_INPUT_EVENT, returns STATUS. Category: self-sent. 

clsScrollbar responds by returning stsControlCancelPreview if the penDown occurred in the shaft. 

Otherwise, the scrollbar self-sends msgControlRepeatPreview so that at least one arrow scroll is done. 

Note that the scrollbar won't receive this message if the penDown occurred in the thumb, because in 
that case clsScrollbar's response to msglnputEvent returned stsInputTerminate (after creating and 
starting an instance of clsTrack). 

msgControlAcceptPreview 

Self-sent when msgPenUp is received. 

Takes P_INPUT_EVENT, returns STATUS. Category: self-sent. 

Comments clsScrollbar responds by notifying its CONTROL_METRICS.client with msgScrollbar[Vert/Horiz] Scroll 

and an action of sbEndScroll. 

Although one might expect this message to be sent when the pen is lifted from a scroll arrow, under 
normal circumstances a scrollbar will never receive this message. This is because clsScrollbar sees the 
msglnputEvent(msgPenUp) and self-sends msgGWinAbort to cancel the gesture (because the user 
really wasn't gesturing over the repeating arrow). clsControl responds to msgGWinAbort by self-sending 
msgControlCancelPreview, which sends out the sbEndScroll. 



itttmerits 
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msgControlCancelPreview 

Self-sent when style.previewGrab is false and msgPenExitDown is received. 

Takes P_INPUT_EVENT, returns STATUS. Category: self-sent. 

Comments clsScrollbar responds by notifying its CONTROL_METRICS.client with msgScrollbar[Vert/Horiz] Scroll 

and an action of sbEndScroll. 



msgControlRepeatPreview 

Self-sent if style. repeatPreview is true. 

Takes PJNPUTJEVENT, returns STATUS. Category: self-sent. 

Comments clsScrollbar responds by notifying its CONTROL_METRICS.client with msgScrollbar[Vert/Horiz] Scroll 

and an action of sbLine [Up/Down] (if the scrollbar is vertical) or sbLine [Left/Right] (if horizontal). 

If the client indicated that no scrolling took place (by not changing the SCROLLBAR_SCROLL. offset 
field), then the scrollbar will return stsControlCancelRepeat. 



msgTrackDone 

Sent by a tracker when it's done. 

Takes P_TRACK_METRICS, returns STATUS. Category: client notification. 

Comments A scrollBar will receive this message when the user has lifted the pen after dragging the thumb. 

If the scrollBar 's style.direction is sbDirectionVertical, the scrollBar will notify its 
CONTROL_METRICS.client with msgScrollbarVertScroll and one of these actions: sbThumbUpDown, 
sbToTop, or sbToBottom. 

If the scrollBar 's style.direction is sbDirectionHorizontal, the scrollBar will notify its 
CONTROL_METRICS. client with msgScrollbarHorizScroll and one of these actions: sbThumbLeftRight, 
sbToLeft, or sbToRight. 
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SELCHMGR.H 



This file contains the API for clsSelChoiceMgr. 

clsSelChoiceMgr inherits from clsManager. 

Provides a choice manager that defines a protocol for managing the selection. Although clients may 
subclass clsSelChoiceMgr and add to or modify its behavior, there should be little reason to do so. 
clsSelChoiceMgr itself implements all of the standard UI for selectable choices. 

Notes: 

The selection choice manager works in a similar manner to the regular choice manager except it causes 
selection feedback to be displayed on the controls it manages. It also tells a client when to acquire the 
selection by sending msgSelChoiceMgrAcquireSel to the client. This message is sent every time one of 
the controls it manages turns on. selchmgr also sends msgSelChoiceMgrNullSel when someone 
programmatically turns off the selected control or sends the selchmgr msgChoiceMgrSetOnButton with 
an argument of objNull. The client should set the selection to null when it recieves this message. 

Note that msgNewDefaults to clsChoice results in a prototypical new struct whose values describe a 
button of contact style bsContactLockOn. This is correct for choices that always have one button on, 
but this is typically not what you'd want for selectable choices—the user should be able to deselect a 
selected button by tapping on it (so the choice then has no buttons on). To acheive this effect, do the 
equivalent of the following: 

Ob jCallWarn (msgNewDefaults, clsChoice, fcchoiceNew) ; 

choiceNew . tkTable . pButt onNew->butt on . style . contact = bsCont act Toggle ; 

choiceNew.tkTable. manager = <uid of a selChoiceMgr>; 

ObjCallRet (msgNew, clsChoice, SchoiceNew, s) ; 

See the documentation for msgTkTableChildDefaults in choice.h. 

When a client receives msgSelYield from the selection manager it should send 
msgSelChoiceMgrNullCurrent to the selchmgr. This will cause it to turn off its currently chosen 
control and set its current choice to null. Here's how a client would typically respond to the relevant 
messages. 

msgSelChoiceMgrAcquireSel : 

<remember what kind of selection self will own 

by writing pArgs->id into self's instance data> 

ObjCallRet (msgSelSelect, self, pNull, s) ; 

<don't call ancestor> 
msgSelChoiceMgrNullSel : 

// The following will result in self receiving msgSelYield. 

ObjCallRet (msgSelSetOwner, theSelectionManager, objNull, s); 

<don't call ancestor> 

msgSelYield: 

// Ignore if self isn't the primary selection owner, 
if ((BOOLEAN) (U32) pArgs == false) 

return ObjectCallAncestorCtx(ctx) ; 
<get the choice by referencing the id value in self s instance data> 
<get the manager of the choice via msgTkTableGetManager> 
ObjCallRet (msgSelChoiceMgrNullCurrent, <manager>, pNull, s) ; 
<clear the id field in self's instance data> 
<don't call ancestor> 
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msgSelOpt ionTagOK : 

<determine whether the kind of option sheet indicated by pArgs 
(a TAG value) could be applied to the selection, and return 
stsOK if so, stsFailed if not> 
<don't call ancestor> 

msgSelOptions : 

<bring up an option sheet for the selection> 
<don't call ancestor> 

See sel.h for additional selection messages and their documentation. 



#ifndef SELCHMGR_INCLUDED 
tdefine SELCHMGR_INCLUDED 

#include <chmgr.h> 
♦include <xfer.h> 
tinclude <win.h> 



tifndef CHMGR_INCLUDED 

tendif 

tifndef XFER_INCLUDED 

tendif 

tifndef WIN_INCLUDED 

tendif 



Common #defines and typedefs 

typedef OBJECT SEL_CHOICE_MGR; 



msgNew 

Creates a selChoiceMgr object. 

Takes P_SEL_CHOICE_MGR_NEW, returns STATUS. Category: class message. 

Arguments typedef struct SEL_CHOICE_MGR_NEW_ONLY { 

OBJECT client; // Object to send acquire/null messages to 
U32 id; // Id tag sent with acquire/null messages 
U32 spare; 
} SEL_CHOICE_MGR_NEW_ONLY, *P_SEL_CHOICE_MGR_NEW_ONLY; 

tdefine selChoiceMgrNewFields \ 
choiceMgrNewFields \ 
SEL_CHOICE_MGR_NEW_ONLY selChoiceMgr; 

typedef struct SEL_CHOICE_MGR_NEW { 

selChoiceMgrNewFields 
} SEL_CHOICE_MGR_NEW, *P_SEL_CHOICE_MGR_NEW; 

typedef struct SEL_CHOICE_MGR_INFO { 

SEL_CHOICE_MGR selChoiceMgr; // Sender 

U32 id; // Client-specified id tag 

WIN button; // Current on button 

} SEL_CHOICE_MGR_INFO, *P_SEL_CHOICE_MGR_INFO; 

Comments The fields you commonly set are: 

pArgs->selChoiceMgr.client An object to manage the selection protocol. (Typically the app uid.) 

pArgs->selChoiceMgr.id An id to distinguish among >1 selectable instances of clsChoice within the 
client's domain. 

msgNewDefaults 

Initializes the SEL_CHOICE_MGR_NEW structure to default values. 

Takes P_SEL_CHOICE_MGR_NEW, returns STATUS. Category: class message. 



Message 
Arguments 



Comments 
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typedef struct SEL_CHOICE_MGR_NEW { 

selChoiceMgrNewFields 
} SEL_CHOICE_MGR_NEW, *P_SEL_CHOICE_MGR_NEW; 

Zeroes out pArgs->selChoiceMgr. 



msgSelChoiceMgrGetClient 



Passes back the client uid held by the receiver. 

Takes P_OBJECT, returns STATUS. 

♦define msgSelChoiceMgrGetClient MakeMsg(clsSelChoiceMgr, 1) 



msgSelChoiceMgrSetClient 

Sets the client uid held by the receiver. 
Takes OBJECT, returns STATUS. 
♦define msgSelChoiceMgrSetClient 



MakeMsg (clsSelChoiceMgr , 2 ) 



msgSelChoiceMgrGetld 

Passes back the id held by the receiver. 
Takes P_U32, returns STATUS. 
♦define msgSelChoiceMgrGetld 



MakeMsg (clsSelChoiceMgr, 3) 



msgSelChoiceMgrSetld 

Sets the id held by the receiver. 
Takes U32, returns STATUS. 
♦define msgSelChoiceMgrSetld 



MakeMsg (clsSelChoiceMgr, 4) 



msgSelChoiceMgrNullCurrent 

Tells the receiver to clear the visuals and state of the choice. 

Takes nothing, returns STATUS. 

♦define msgSelChoiceMgrNullCurrent MakeMsg (clsSelChoiceMgr, 5) 

Comments After receiving this message, the choice will have no current value. This message does not result in the 

sending of any side-effect messages such as msgSelYield. 



cIsChoiceMgr Messages to which 
selChoiceMgrs Respond 



msgChoiceMgrGetOnButton 

Gets the current on button. Passes back objNull if no button is on. 
Takes P_UID, returns STATUS. 
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msgChoiceMgrSetOnButton 

Sets the current on button. 

Takes UID, returns STATUS. 

Since the choiceMgr will use msgControlSetValue to turn the button on, that button's normal 
notification protocol will be invoked. 

All buttons are turned off if message argument is objNull. 



Client Messages 



les. 



msgSelChoiceMgrAcquireSel 

Sent to the client whenever a different button is selected. 

Takes P_SEL_CHOICE_MGR_INFO, returns STATUS. Category: client responsibility. 

#define msgSelChoiceMgrAcquireSel MakeMsg(clsSelChoiceMgr, 6) 



typedef struct SEL_CHOICE_MGR_INFO { 
rguments SEL_CHOICE_MGR selChoiceMgr; // Sender 

U32 id; // Client-specified id tag 

WIN button; // Current on button 

} SEL_CHOICE_MGR_INFO, *P_SEL_CHOICE_MGR_INFO; 

ommemfs The client would typically respond by doing the following: 

<remember what kind of selection self will ownby writing pArgs->id into selfs instance data> 

ObjCallRet(msgSelSelect, self, pNull, s); 

<don't call ancestor> 



msgSelChoiceMgrNullSel 

Sent to the client whenever a different button is selected. 

Takes P_SEL_CHOICE_MGR_INFO, returns STATUS. Category: client responsibility. 

tdefine msgSelChoiceMgrNullSel MakeMsg(clsSelChoiceMgr, 7) 

typedef struct SEL_CHOICE_MGR_INFO { 

SEL_CHOICE_MGR selChoiceMgr; // Sender 

U32 id; // Client-specified id tag 

WIN button; // Current on button 

} SEL_CHOICE_MGR_INFO, *P_SEL_CHOICE_MGR_INFO; 

The client would typically respond by doing the following: 
ObjCallRet(msgSelSetOwner, theSelectionManager, objNull, s); 
<don't call ancestor> 
As a consequence of this, the client would then receive msgSelYield. 
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SHADOW.H 



This file contains the API definition for clsShadow. 
clsShadow inherits from clsCustomLayout. 

Implements a true shadow as a separate window underneath the shadowed window. 



#ifndef SHADOW_INCLUDED 
tdefine SHADOW_INCLUDED 

#include <clayout.h> 



#ifndef _INCLUDED 
#endif 



I Common #defines and typedefs 



typedef OBJECT SHADOW; 
typedef struct SHADOW_STYLE { 

U16 trueShadow : 1, // create a window for true- shadow effect 
spare : 15; // unused (reserved) 
} SHADOW STYLE, *P SHADOW STYLE; 



JF Messages 



msgNew 

Creates in instance of clsShadow. 

Takes P_SHADOW_NEW, returns STATUS. Category: class message. 

Arguments typedef struct SHADOW_NEW_ONLY { 

SHADOW_STYLE style; 
WIN borderWin; 

U32 spare; // unused (reserved) 

} SHADOW_NEW_ONLY, *P_SHADOW_NEW_ONLY; 

tdefine shadowNewFields \ 

customLayoutNewFields \ 

SHADOW_NEW_ONLY shadow; 

typedef struct SHADOW_NEW { 

shadowNewFields 
} SHADOW_NEW, *P_SHADOW_NEW; 

Comments If pArgs->win.flags.style has wsTransparent on, clsShadow will do the following: 

♦ set border.style.getDeltaWin for pArgs->shadow.borderWin to true. This will forward any 
drag/resize operations on the border window to the shadow window. 

♦ if pArgs->shadow.style.trueShadow is true the following is done: 

if pArgs->shadow.shadowWin is objNull, an instance of 
clsBorder is created as the true shadow window. 

sel f s pArgs->border.style.shadow/resize are copied 

to shadowWin s border style. Also, border.style.getDeltaWin 

for shadowWin is set to true. 
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shadowWin is inserted as a child of self, underneath the borderWin, 
if any. 

If pArgs->borderWin is not objNull, the wsShrmkWrapWidth/Height window flags of the borderWin 
are changed to match self's and the borderWin is inserted as a child of self, above the shadowWin. 



msgNewDefaults 



Message 
Ar§yme«ifs 



Comments 



Initializes the SHADOW_NEW structure to default values. 

Takes P_SHADOW_NEW, returns STATUS. Category: class message. 

typedef struct SHADOW_NEW { 

shadowNewFields 
} SHADOW_NEW, *P_SHADOW_NEW; 

Zeroes out pArgs->shadow and sets 

pArgs->win. flags. input |- inputDisable | input Transparent; 

pArgs->win. flags. style |= wsTransparent | wsGrowBottom | wsGrowRight; 

pArgs->gWin. style. gestureEnable = false; 

pArgs->border. style. edge = bsEdgeAll; 

pArgs->border . style . shadow = bsShadowThickGray ; 

pArgs->border. style. shadowGap = bsGapWhite; 

pArgs->border. style. border Ink = bsInkGray66; 

pArgs->border. style. resize = bsResizeCorner; 

pArgs->border. style. drag = bsDragHoldDown; 

pArgs->border. style. top = bsTopUp; 

pArgs->customLayout. style. limitToRootWin = true; 

Default SHADOW_STYLE: 

trueShadow = false 



msgShadowGetStyle 

Passes back the current style values. 

Takes P_SHADOW_STYLE, returns STATUS. 

♦define msgShadowGetStyle MakeMsg(clsShadow, 1) 

Message typedef struct SHADOW_STYLE { 

Arguments U16 trueShadow : 1, // create a window for true-shadow effect 

spare : 15; // unused (reserved) 

} SHADOW_STYLE, *P_SHADOW_STYLE; 

msgShadowSetStyle 

Sets the style values. 

Takes P_SHADOW_STYLE, returns STATUS. 

♦define msgShadowSetStyle MakeMsg(clsShadow, 2) 

Messoge typedef Struct SHADOW_STYLE { 

Argumerti-s U16 trueShadow : 1, // create a window for true-shadow effect 

spare : 15; // unused (reserved) 

} SHADOW_STYLE, *P_SHADOW_STYLE ; 

Comments Changes in self's border style are passed on to the borderWin and shadowWin. 



msgShadowGetBorderWin 

Passes back the border window. 
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Takes P_WIN, returns STATUS. 
tdefine msgShadowGetBorderWin 



MakeMs g ( c 1 s Shadow , 3 ) 



Comments 



msgShadowSetBorderWin 



Sets the border window. 

Takes WIN, returns STATUS. 

tdefine msgShadowSetBorderWin MakeMsg (clsShadow, 4) 

The new borderWin is altered as in msgNew. 



msgShadowGetShadowWin 

Passes back the shadow window. 

Takes PJXTN, returns STATUS. 
tdefine msgShadowGetShadowWin 



MakeMsg (clsShadow, 5) 



Messages from Other Classes 



msgWinSetFlags 

Sets the window flags. 

Takes P_WIN_METRICS, returns STATUS. 

Comments clsShadow will alter the borderWin's window flags to match the wsShrinkWrapWidth/Height flags of 

self. 



msgCstmLayoutGetChildSpec 

Passes back the current spec for the specified child. 

Takes P_CSTM_LAYOUT_CHILD_SPEC, returns STATUS. Category: self-sent. 

Comments clsShadow responds by providing the custom layout constraints for borderWin and shadowWin. 

The shadowWin is placed and sized to provide a gap area on the lower-left and upper-right. 

The borderWin is placed above the bottom shadow of the shadowWin and sized width-wise to extend 
to the left of the right shadow of the shadowWin. 

msgWinRepaint 

Tells a window to repaint itself. 

Takes nothing, returns STATUS. Category: descendant responsibility. 

Comments If self has wsTransparent on, clsShadow prevents any painting by not calling ancestor and painting 

nothing. 
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STDMSG.H 



This file contains the API definition for the standard message package. 
The functions described in this file are contained in SYSUTIL.LIB. 

^Introduction 

The standard message package makes it easy to display error messages, modal dialog boxes, and progress 
notes. The package hides many of the details of finding resources and creating UI objects. The package 
uses clsNote to display messages. (See note.h.) 

Message are stored as strings in string array resources. A 32 bit value identifies the proper resource. For 
error messages the value is a STATUS; for dialog boxes and progress notes the value is a TAG constructed 
using the MakeDialogTag macro. 

*V Road Map 

To display a dialog box, use: 

♦ StdMsg 

To display an error message when you know about the error, use: 

♦ StdError 

To display an error message when you don't know about the error, use: 

♦ StdUnknownError 

To display a progress note, use: 

♦ StdProgressUp 

♦ StdProgressDown 

To display messages extracted from a specified resource file or path, use: 

♦ StdMsgRes 

♦ StdErrorRes 

To construct a customized message, use: 

♦ StdMsgCustom 
PenPoint-internal use only: 

♦ StdSystemError 
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Pjr A Typical Scenario 

[This scenario illustrates some features of the package that haven't been described yet. See the sections 
"Button Definition" and 'Text Substitution and Formatting" for more information.] 

The first step in using the standard message package is to define a tag or status for each string: 

// #define stsFooErrorl MakeStatus (clsFoo, 0) 
// #define stsFooError2 MakeStatus (clsFoo, 1) 

// #define tagFooDialogl MakeDialogTag (clsFoo, 0) 
// #define tagFooDialog2 MakeDialogTag (clsFoo, 1) 

The next thing to do is to construct resources which contain the text strings. Standard message strings 
live in string array resources (see resfile.h). Application string arrays should reside in the application s 
app.res file. (PenPoint's string arrays reside in penpoint.res.) 

There is one string array for error strings and another separate array for dialog box and progress strings. 
A single string array resource holds all of the strings for a given class. 

Typically the string arrays are defined in a .re file which is compiled with the PenPoint SDK's resource 
compiler. The position of each string in the string array resource must match its tag or status index 
(starting from 0). 

static P_STRING errorClsFoo [ ] = { 

"This is the first error message.", 

"[Retry] [Cancel] This is the second error message, count: A ld"}; 

static P_STRING dialogClsFoo [ ] = { 

"This is the first dialog message.", 

"[Go] [Stop] This is the second dialog message, str: A ls"}; 
static RCJENPUT errorTabClsFoo = { 

resForStdMsgError (clsFoo) , errorClsFoo, 0, resStringArrayResAgent}; 
static RC_INPUT dialogTabClsFoo = { 

resForStdMsgDialog (clsFoo) , dialogClsFoo, 0, resStringArrayResAgent}; 

P_RC_INPUT res Input [] = { 

6errorTabClsFoo, // String array for std msg error strings 
fcdialogTabClsFoo, // String array for other std msg strings 
pNull}; 

Finally create a note by simply calling one of the appropriate function. This example uses StdMsgO, 
StdError() and StdUnknownError(). 

buttonHit = StdMsg(tagFooDialog2, "String"); 
s = Ob jectCall (...); 
if (s < stsOK) { 

if (s == stsFooErrorl) { 

StdError (stsFooErrorl) ; 
} else { 

StdUnknownError (s) ; 
} 
} 

P^ Button Definition 

Message strings may contain button definitions. A button definition is a substring enclosed in square 
brackets at the beginning of the message string. Any number of buttons may be defined but all buttons 
must appear at the front of the string. If no buttons are defined then a single "OK" button is created. 

StdMsgO, StdError(), StdMsgRes(), StdErrorRes() and StdSystemError() return the button number that 
the user hit to dismiss the note. Button numbers start with 0. For example, a note constructed with the 
following string: 
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"[ButtonO] [Buttonl] [Button2] Here's your message!" 

returns the value 1 if the user hits Buttonl. These functions might also return a negative error status if a 
problem occurred inside the function. 

See the section "A Typical Scenario" for an example. 

PJr Text Substitution and Formatting 

Message strings may contain parameter substitutions, as defined in cmpstext.h. Text substitution also 

works inside the button substrings. t 

See the section "A Typical Scenario" for an example. £ 

You can break your message up into paragraphs by putting 2 newlines at the paragraph breaks. For 5 

example: * 

"Here's the first paragraph. \n\nHere's the second one." 

fy Progress Notes 

Clients can put up a progress note to inform the user that a lengthy operation has begun, and take down 
the progress note to indicate that the operation has been completed. 

Cancellation of the operation is not supported in PenPoint 1.0. Progress notes do not have buttons. 
Here's an example of progress indication usage: 

SP_T0KEN token; 

StdProgressUp(tagFooProgressl, fctoken, pararal, param2); 
. . . Lengthy operation ... 
StdProgressDown(fctoken) ; 

P^ Searching for Resources 

Most of the functions in this package search for resources as follows: 

♦ If the process is an application process (OSThisAppO returns non-null), then the applications 
resource list is searched. Otherwise theSystemResFile is searched. 

♦ If the desired resource is not found in the above resource files or lists, then theServiceResList is 
searched. 

The exceptions to this rule are: 

♦ StdSystemError(), which only checks theSystemResFile. 

♦ StdMsgRes(), which takes as one of its parameters the resource file or list to search. 

♦ StdErrorRes(), which takes as one of its parameters the resource file or list to search. 

Jjr Note Titles and Reference Field 

Notes will be titled "Note from {App}..." if the string was found in the app resource file, or "Note from 
PenPoint..." if the string was found in the system resource file. 

You can use StdMsgCustom() if you want to have some other title. 

Error messages will also have an additional line at the bottom of the note of the form: 

Reference: xxx-xxx 

where xxx-xxx is the status code that generated the error. 
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Pjr Customization of Standard Message Package Notes 

StdMsgCustom() allows clients to customize a standard message package note. It returns the note object, 
without displaying it. Developers can modify this object as they wish and then display it themselves. 

tifndef STDMSG_INCLUDED 
tdefine STDMSG_INCLUDED 

tifndef GO_INCLUDED 
♦include <go.h> 
tendif 

tifndef OSTYPES_INCLUDED 
tinclude <ostypes.h> 
tendif 

Common #defines 

P^ Constructing Standard Message Tags 

Use MakeStatus() (defined in go.h) to construct string tags for errors. 

Use MakeDialogTagO to construct string tags for dialog and progress strings. 

tdefine MakeDialogTag(wkn, index) MakeIndexedResId(wkn, 1, index) 

Pjr Constructing Standard Message Resource Ids 

Tn a .re. file, use resForStdMsgDialog to construct the resource id for a class's dialog string array. Use 
resForStdMsgError to construct the resource id for a class's error string array. 

See the section "A Typical Scenario" for an example. 

tdefine resForStdMsgDialog (wkn) MakeListResId(wkn, resGrpStdMsg, 1) 
tdefine resForStdMsgError (wkn) MakeListResId(wkn, resGrpStdMsg, 0) 

^Public Functions 

StdUnknownError 

Displays an error message when the client doesn't recognize the error. 

Returns STATUS. 

Function Prototype STATUS CDECL StdUnknownError ( 
STATUS status); 

Comments Use this function to display an error message when the error status is one that you don't pay special 

attention to. 

StdUnknownError searches for an error message that matches the status parameter. If the specified status 
isn't found then a note with just the error code is displayed. 

StdUnknownError does not allow parameter substitution or multiple command buttons. Any parameter 
substitution specifications in the text are replaced with "???". A single "OK" command button is always 
displayed. 

See the section "A Typical Scenario" for an example. See the section "Searching for Resources" for a 
description of which resource files are searched. 
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StdMsg 

Displays a dialog box from a resource file. 
Returns S32. 

Function Prototype S32 CDECL StdMsg ( 
const TAG tag, 
. . . ) ; 

Comments Use this function to display a dialog box. 

StdMsg searches for an dialog string that matches the tag parameter. A dialog box with the message and 
buttons defined in the message string is displayed. 

See the section "A Typical Scenario" for an example. See the section "Searching for Resources" for a 
description of which resource files are searched. 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

ieturn v«iye stsResResourceNotFound the specified tag is not found. 

< stsOK some other error occurred. 

>= stsOK number of button the user hit (0 based). 

StdError 

Displays an error message from a resource file. 
Returns S32. 

Function Prototype S32 CDECL StdError ( 

const STATUS status, 
. . . ) ; 

Comments Use this function to display an error message. 

StdError searches for an error message string that matches the status parameter. A note with the message 
and buttons defined in the error message string is displayed. The note also contains an Error Code 
number line. 

See the section "A Typical Scenario" for an example. See the section "Searching for Resources" for a 
description of which resource files are searched. 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

Return Vcsiye StsResResourceNotFound the specified tag is not found. 

< stsOK some other error occurred. 

>= stsOK number of button the user hit (0 based). 

StdSystemError 

For PenPoint internal use only. Displays an error message for a standard PenPoint error. 

Returns S32. 

Function Prototype S32 CDECL StdSystemError ( 
const STATUS status, 
. . . ) ; 
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Comments StdSystemError searches theSystemResFile (penpoint.res) for an error message string that matches the 

status parameter. A note with the message and buttons defined in the string is displayed. 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

Return Volu© stsResResourceNotFound the specified tag is not found. 

< stsOK some other error occurred. 

>= stsOK number of button the user hit (0 based). 

StdProgressUp 

Displays a progress note from a resource file. 

Returns STATUS. 

Arguments typedef struct SP_T0KEN { 

OBJECT uid; 

OS_MILLISECONDS start Time; 
U32 spare [8]; 

} SPJFOKEN, *P_SP_T0KEN; 

Function Prototype STATUS CDECL StdProgressUp ( 
const TAG tag, 

P_SP_T0KEN pToken, 



Comments 



Return Value 
See Abo 



Use this function to inform the user that a lengthy operation has started. 

StdProgressUp searches for an dialog message that matches the tag parameter. A dialog box with the 
message string is displayed. This dialog box stay ups until StdProgressDown is called. 

The pToken parameter, as filled in by StdProgressUp, must be passed to StdProgressDown. The client 
shouldn't touch it! 

Example: 

SPJTOKEN token; 

StdProgressUp (tagFoo, &token, paraml, param2); 

StdProgressDown (&token) ; 

Progress notes do not contain a command bar. Any button definitions are ignored. 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

See the section "Progress Notes" for more information. See the section "Searching for Resources" for a 
description of which resource files are searched. 

StsResResourceNotFound The specified tag was not found 

StdProgressDown 



StdProgressDown 

Brings down a progress note that was put up with StdProgressUp(). 
Returns STATUS. 



Function Prototype STATUS CDECL StdProgressDown ( 
P_SP_T0KEN pToken) ; 



Comments 



The pToken parameter must be the same as that passed to StdProgressUp (). 
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See Also 



See the section "Progress Notes" for more information. 
StdProgressUp 



StdMsgRes 

Just like StdMsgO except that the resource path is specified. 
Returns S32. 

Function Prototype S32 CDECL StdMsgRes ( 



const 



OBJECT 
TAG 
. . • ) ; 



resFile, 
tag, 



Comments 



Return Vofye 



See Also 



Use StdMsgRes when you need the functionality of StdMsg, but need to look up the string in a specified 
resource file or resource list. 

StdMsgRes searches the specified resource file or list for a dialog message string that matches the tag 
parameter. A dialog box with the message and buttons defined in the message string is displayed. 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

stsResResourceNotFound the specified tag is not found. 

< stsOK some other error occurred. 

>= stsOK number of button the user hit (0 based). 

StdMsg 



StdErrorRes 

Just like StdError() except that the resource path is specified. 
Returns S32. 



Function Prototype S32 CDECL StdErrorRes ( 

OBJECT resFile, 
const STATUS status, 



Comments 



Return Value 



See Also 



Use StdMsgError when you need the functionality of StdError, but need to look up the string in a 
specified resource file or resource list. 

StdErrorRes searches the specified resource file or list for an error message string that matches the status 
parameter. A note with the message and buttons defined in the error message string is displayed. 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

StsResResourceNotFound the specified tag is not found. 

< stsOK some other error occurred. 

>= stsOK number of button the user hit (0 based). 

StdError 



StdMsgCustom 

Creates a note object in the manner of StdMsgQ. 
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Returns OBJECT. 

Function Prototype OBJECT CDECL StdMsgCustOItl ( 

OBJECT resFile, 
const TAG tag, 

Comments Use StdMsgCustom when you want to create a note using the facilities of the standard message package 

but need to customize the note before displaying it. 

The client is responsible for displaying the note object. The note has autoDestroy on, so it self-destructs 
when dismissed. 

StdMsgCustom allows the specification of a resource file or list to search. If resFile is objNull then 
searching occurs as described in the section "Searching for Resources." The tag parameter can either be a 
dialog tag (created with MakeDialogTagO) or an error status (created with MakeStatusO). 

Here's an example: 

♦define tagFooDialogl MakeDialogTag(clsFoo, 0) 

S32 buttonHit; 
OBJECT note; 

note = StdMsgCustom (objNull, tagFooDialogl, argl, arg2) ; 
if (note == objNull) { 

... // Handle error, probably resource not found. 

goto error; 
} 

...II Customize the note. 
ObjCallRet (msgNoteShow, note, SbuttonHit, s) ; 

Like printf, this function takes a variable number of parameters. There is no error checking on the 
number and type of the parameters. 

Return Value objNull No match, or some other error occurred. 
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STRLBOX.H 



This file contains the API for clsStringListBox. 
clsStringListBox inherits from clsListBox. 

Implements a listbox that behaves as a choice or a group of toggles. 

As with clsListBox, the client supplies entry information on demand. With clsStringListBox, however, 
the client supplies strings, not windows. These strings are used to create instances of clsButton, and it is 
these buttons that are used as entry windows within the listBox. 

A stringListBox may behave in one of three manners: as a list of individual toggles (as in 
clsToggleTable), as choice that has zero or one of its buttons 'on' at a time, or as a choice that always has 
exactly one of its buttons 'on' at once. When a stringListBox is behaving as a choice, its value is the 
'data' field of the entry that is currently chosen. 



♦ifndef STRLBOX_INCLUDED 
♦define STRLBOX_INCLUDED 

♦include <listbox.h> 



tifndef LISTBOX_INCLUDED 
♦endif 



Common #defines and typedefs 



// String ListBox behavior styles 



♦define slbRoleToggles 
♦define slbRoleChoiceOl 1 
♦define slbRoleChoicel 2 


// 
// 
// 


// String ListBox entry looks 
♦define slbLooklnvert 
♦define slbLookDecorate 1 


// 
// 


typedef struct { 
U16 role 
look 
dirty 
spare 

} STRLB_STYLE, *P_STI 


4, 
2, 
1, 
9; 
ILB STYLE; 


// 
// 
// 
// 


Default STRLB_STYLE: 




role = slbRol* 
look = slbLool 
dirty = false 


^Toggles 
clnvert 





(roles) 

Act like a toggle table. 
Act like a choice ( <=1 entries chosen) 
Act like a choice (always 1 entry chosen) 

Chosen entries have inverted appearance. 
Chosen entries have decorated appearance. 

Overall behavior. 
Controls looks of entries. 
Dirty status (ref. control. h) 
reserved 



ftrgwwersfs 



msgNew 

Creates a string listbox window. 

Takes P_STRLB_NEW, returns STATUS. Category: class message. 



typedef struct { 
STRLB_STYLE 
U32 



style; // overall style 

value; // initial value (if slbRoleChoiceOl 

//or slbRoleChoicel) 
U32 spare; // reserved 

} STRLB_NEW_ONLY, *P_STRLB_NEW_ONLY; 

The value is the 'data' field of the entry that is currently chosen. 



556 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 

♦define stringListBoxNewFields \ 
listBoxNewFields \ 

STRLB_NEW_ONLY stringListBox; 

typedef struct { 

StringListBoxNewFields 
} STRLB_NEW, *P_STRLB_NEW; 
fdefine stsStrListBoxNoValue MakeStatus (clsStringListBox, 1) 

Comments The fields you commonly set are: 

pArgs->stringListBox.style.role overall behavior 

pArgs->stringListBox.style.look entry looks 

pArgs->stringListBox. value initial value 

msgNewDefaults 

Initializes the STRLB_NEW structure to default values. 

Takes P_STRLB_NEW, returns STATUS. Category: class message. 

Message typedef struct { 

Arguments StringListBoxNewFields 

} STRLB NEW, *P STRLB NEW; 



msgStrListBoxGetStyle 

Passes back the style of the receiver. 
Takes P_STRLB_STYLE, returns STATUS. 
#define msgStrListBoxGetStyle 



MakeMsg (clsStringListBox, 1) 



Message 


typedef struct { 






Arguments 


U16 role 


4, 


// Overall behavior. 




look 


2, 


// Controls looks of entries. 




dirty 


1, 


// Dirty status (ref. control. h) 




spare 


9; 


// reserved 



STRLB STYLE, *P STRLB STYLE; 



msgStrListBoxGetDirty 

Passes back true if the listbox has been altered since dirty was set false. 

Takes P.BOOLEAN, returns STATUS. 

tdefine msgStrListBoxGetDirty MakeMsg (ClsStringListBox, 2] 



msgStrListBoxSetDirty 

Sets the dirty bit of a string listbox. 
Takes BOOLEAN, returns STATUS. 

tdefine msgStrListBoxSetDirty MakeMsg (clsStringListBox, 3) 

Comments The receiver will send msgControlSetDirty(pArgs) to every entry window. 
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msgStrListBoxGetValue 

Passes back the value of a string listbox. 

Takes P_U32, returns STATUS. 

♦define msgStrListBoxGetValue MakeMsg (clsStringListBox, 4) 

Comments The value is the data field of the entry that is currently chosen. This message may be used on instances 

whose role is either slbRoleChoiceOl or slbRoleChoicel. For instances whose role is slbRoleToggles, 
use msgListBoxEnum with enum. flags set to lbSelected. 

Return Value stsFailed the role is set to slbRoleToggles. g 

O 
stsStrListBoxNoValue there's no entry selected. 

msgStrListBoxSetValue 

Sets the value of a string listbox whose role is one of slbRoleChoice*. 

Takes U32, returns STATUS. 

♦define msgStrListBoxSetValue MakeMsg (clsStringListBox, 5) 

Comments Will deselect any selected entry if the arg is maxU32 and the role is set to slbRoleChoicel. For instances 

whose role is slbRoleToggles, send as many msgListBoxSetEntry messages as required. 

Return Value stsFailed the role is set to slbRoleToggles. 



Client Messages 



msgStrListBoxProvideString 

This message requests the client (or subclass) to provide a string. 

Takes P_STRLB_PROVIDE, returns STATUS. Category: self-sent/client responsibility. 

♦define msgStrListBoxProvideString MakeMsg (clsStringListBox, 6) 

Arguments typedef struct { 

OBJECT strListBox; // In: requestor 

U16 position; // In: position of requested entry 

P_CHAR pString; // Out: a 256 byte buffer for the string 

U32 data; // Out: data for the entry 

U32 spare; // reserved 

} STRLB_PROVIDE, *P_STRLB_PROVIDE ; 

Comments This message is sent when clsStringListBox receives msgListBoxProvideEntry. 

The string listbox is constructing an entry to be put into the listbox, and it needs the string and some 
data for the entry. The client (or subclass) should copy the string bytes into the pString buffer, and set 
the data field as desired. 

msgStrListBoxProvideString is sent first to the string listbox itself. If the message reaches the standard 
clsStringListBox message handler, this message is forwarded on to the client of the listbox. 

A string listbox will send this message even when the position it's asking for is >= the number of entries 
specified for the listBox (same behavior as msgListBoxProvideEntry). In this case, the client is free to 
return a non-zero status value, indicating to the string listbox that no entry should be created for that 
position. Providing another string in this case allows A listBox will send this message even when the 
position it's asking for is >= the number of entries specified for the listBox. In this case, the client is free 
to return a non-zero status value, indicating to the listBox that no entry should be created for that 
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position. Providing another entry window in this case allows the user to create new entries by merely 
scrolling past the end of the list. 

Subclasses of clsStringListBox may choose to respond to msgStrListBoxProvideString, or bypass this 
mechanism altogether and respond instead to msgListBoxProvideEntry. 

msgStrListBoxNotify 

This message is sent out whenever the value of a string listbox changes. 

Takes U32, returns STATUS. Category: self-sent/client responsibility. 

♦define msgStrListBoxNotify MakeMsg (clsStringListBox, 7) 

Comments The pArgs will be undefined when role is set to slbRoleToggles (use msgListBoxEnum with enum.flags 

set to lbSelected). 

clsStringListBox responds by forwarding the message to the client of the listbox. 



r Messages from Other Classes 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

comments clsStringListBox responds by filing away its style and value. Note that clsListBox will have filed its data 

first according to the value of LIST_BOX_STYLE.filing. 



Comments 



msgRestore 

Creates and restores an object from an object file. 
Takes P_OBJ_RESTORE, returns STATUS. 
clsStringListBox responds by restoring its style and value. 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes P_WIN_SEND, returns STATUS. 

Comments clsStringListBox responds when pArgs->msg is msgButtonBeginPreview, msgButtonCancelPreview, or 

msgButtonDone. If pArgs->msg is anything else, clsStringListBox just returns the result of calling its 
ancestor. 

For these three messages, clsStringListBox will make the set of entry windows act as a group (as does 
clsChoiceMgr) and return stsManagerContinue. 

Rety m Value stsManagerContinue returned for one of the above three messages. 



msgListBoxProvideEntry 

Self-sent when a listBox needs a window for display. 

Takes P_LIST_BOXJ£NTRY, returns STATUS. Category: self-sent/client responsibility. 
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Comments clsStringListBox responds by self-sending msgStrListBoxProvideString, using the resulting information 

to create an instance of clsButton, and passing back the new button in pArgs->win. 



msgListBoxAppendEntry 

Appends an entry to the list box after the specified position. 

Takes P_LIST_BOX_ENTRY, returns STATUS. 

Comments clsStringListBox responds by keeping its state in synch—if the position that is currently on is greater 

than the new entry, it's incremented. 

msgListBoxInsertEntry 

Insert an entry to the list box before the specified position. 

Takes P_LIST_BOX_ENTRY, returns STATUS. 

Comments clsStringListBox responds by keeping its state in synch—if the position that is currently on is greater 

than the new entry, it's incremented. 

msgListBoxRemoveEntry 

Removes an entry from the list box. 

Takes U16, returns STATUS. 

Comments clsStringListBox responds by keeping its state in synch— if the position that is currently on is less than 

the new entry, it's decremented. 

If the entry being removed is the current 'on' button, the receiver sets its current value to zero (if the role 
is slbRoleChoicel) or to maxU32 (if the role is slbRoleChoicel). msgStrListBoxNotify will be sent. 



msgListBoxSetEntry 

Sets an entry's information. 
Takes P_LIST_BOX_ENTRY, returns STATUS. 
Comments clsStringListBox responds by setting the tag and data for any new replacement entry window. 
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This file contains the API definition for clsScrollWin. 

clsScrollWin inherits from clsBorder. 

A scrollWin positions, sizes, and displays a client window (optionally part of a "deck" of other child 
windows) together with optional scrollbars, and can scroll the client window by repositioning it. 



P^ Debugging Flags 



The clsScrollWin debugging flag is '%'. Defined values are: 
flag6 (0x0040) layout 



#ifndef SWIN_INCLUDED 
tdefine SWIN_INCLUDED 

#include <sbar.h> 



#ifndef SBAR_INCLUDED 
tendif 



Common #defines and typedeffs 



typedef OBJECT SCROLL WIN; 



^ Client styles for scrollbar client 



#define swClientScrollWin 

#define swClientWin 1 

tdefine swClientOther 2 

// 3 



// scrollWin is the scrollbar client 

// clientWin is the scrollbar client 

// scrollWin will not set the client 

// unused (reserved) 



Alignment styles 



tdefine swAlignLeft 
tdefine swAlignCenter 
tdefine swAlignRight 
tdefine swAlignTop 
tdefine swAlignBottom 
tdefine swAlignSelf 






// left-justified 


1 


// centered 


2 


// right- justified 


swAlignLeft 


// top-justified 


swAlignRight 


// bottom- justified 


3 


// clientWin will align itself 



Jfr Forward styles 



tdefine swForwardNone 
tdefine swForwardGesture 1 
tdefine swForwardXList 2 

typedef struct SCROLL_WIN_STYLE { 



U16 vert Scrollbar 
horizScrollbar 
autoVertScrollbar 
autoHorizScrollbar 
maskScrollbars 
expandChildWidth 
expandChildHeight 
contract Chi ldWidth 
contract ChildHeight 



1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 
1, 



II don't forward anything 
// forward msgGWinGesture 
// forward msgGWinXList 

// vertical scrollbar on/off 

// horizontal scrollbar on/off 

// vert scrollbar on/off based on clientWin 

// horiz scrollbar on/off based on clientWin 

// mask out vertScrollbar and horizScrollbar 

// expand the child's width to avail width 

// expand the child's height to avail height 

// contract the child's width to avail width 

// contract the child's height to avail height 
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getDelta 
getSize 

wideVertScrollbar 
wideHorizScrollbar 
forward 
maskAll 
U16 xAlignment 
yAlignment 
vertClient 
horizClient 
xAlignRigorous 
yAlignRigorous 
privatel 

spare 1 : 

U16 spare2 : 

} SCROLL_WIN_STYLE, *P_SCROLL 

Default SCROLL WIN STYLE: 



2, 



1, 
1, 
1, 



1, // send msgScrollWinProvideDelta to client 

1, // send msgScrollWinProvideSize 

1, // make the vertical scrollbar wide 

1, // make the horizontal scrollbar wide 

2, II what to forward from margins to clientWin 
1; // mask out maskScrollbars 

// x Alignment if innerWin wider than clientWin 
2, II y Alignment if innerWin taller than clientWin 
2, // choice of vertical sb client 
2, // choice of horizontal sb client 

// use xAlignment continuously 

// use yAlignment continuously 
// private 

5; // unused (reserved) 
16; // unused (reserved) 
WIN STYLE; 



getDelta 

vertScrollbar 

horizScrollbar 

autoVert Scrollbar 

autoHorizScrollbar 

expandChildWidth 

expandChildHeight 

vertClient 

horizClient 

xAlignment 

yAlignment 

getSize 

contractChildWidth 

contractChildHeight 

forward 

maskScrollbars 

xAlignRigorous 

yAlignRigorous 



false 

false 

false 

true 

true 

false 

false 

swClientScrollWin 

swClientScrollWin 

swAlignLeft 

swAlignTop 

false 

false 

false 

swForwardNone 

false 

true 

true 



The x- and yAlignment styles are used primarily when the innerWin is wider/ taller than the clientWin. 
However, they are also used when a clientWin that is wider/taller than the innerWin is changing size. In 
this case, the innerWin alters the origin to compensate for the size change so that the appropriate edge 
of the clientWin is held fixed (either by doing the math itself or sending out msgScrollWinAlign if the 
alignment is set to swAlignSelf). An example: a top-aligned clientWin of height 100 in an innerWin of 
height 50 is growing by 20. The innerWin would subtract 20 from the clientWin's new origin.y. 

Clients can disable the adjustments that occur in the second case (clientWin is wider/taller than the 
innerWin) by setting the appropriate x- or yAlignRigorous flag to false. 



typedef struct SCROLL_WIN_METRICS { 

SCROLL_WIN_STYLE style; 

OBJECT client ; 

WIN clientWin; 

U16 colDelta, rowDelta; 

U32 spare 1; 

U32 spare2; 

} SCROLL_WIN_METRICS, *P_SCROLL_WIN_METRICS; 
typedef struct SCROLL WIN DELTA { 



// style bits 

// for msgScrollWinProvideDelta 

// current window to scroll 

// metrics in device units 

// unused (reserved) 

// unused (reserved) 



SCROLL WIN 


scrollWin; 


// 


SCROLLBAR ACTION 


action- 


// 


S32 


offset ; 


// 


RECT32 


viewRect; 


// 


S32 


lineCoord; 


// 


U32 


spare; 


// 


} SCROLL WIN DELTA, *P 


_SCROLL_WIN_I 


)ELT 



in: requesting scroll win 

in: action to resolve 

in: current or new offset 

in/out: viewable portion of clientWin 

in: line coordinate, if any 

unused (reserved) 
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P' Messages 



msgNew 

Creates a scrollWin. 

Takes P_SCROLL_WIN_NEW, returns STATUS. Category: class message. 

typedef SCROLL_WIN_METRICS SCROLL_WIN_NEW_ONLY, *P_SCROLL_WIN_NEW_ONLY; 

#define scrollWinNewFields \ 

borderNewFields \ 

SCROLL_WIN_NEW_ONLY scrollWin; 

Arguments typedef Struct SCROLL_WIN_NEW { 

scrollWinNewFields 
} SCROLL_WIN_NEW, *P_SCROLL_WIN_NEW; 

Comments The fields you commonly set are: 

pArgs->scrollWin.style appropriate style values 

pArgs->scrollWin.clientWin a window to scroll 



msgNewDefaults 

Initializes the SCROLL_WIN_NEW structure to default values. 

Takes P_SCROLL_WIN_NEW, returns STATUS. Category: class message. 

typedef struct SCROLL_WIN_NEW { 

scrollWinNewFields 
} SCROLL_WIN_NEW, *P_SCROLL_WIN_NEW; 

Zeroes out pArgs->scrollWin and sets: 

pArgs->win. flags. style |= wsSendFile | wsClipChildren | wsClipSiblings; 
pArgs->win. flags. style &= ~wsParentClip; 

pArgs->scrollWin. style. autoVertScrollbar = true; 
pArgs->scrollWin. style. autoHorizScrollbar = true; 
pArgs->scrollWin . style . xAlignRigorous = 
pArgs->scrollWin.style.yAlignRigorous = true; 
pArgs->scrollWin.colDelta =10; 
pArgs->scrollWin.rowDelta = 10; 



Message 
Arguments 



Comments 



sessoge 
Arguments 



msgScrollWinGetStyle 

Passes back the current style values. 

Takes P_SCROLL_WIN_STYLE, returns STATUS. 

Idefine msgScrollWinGetStyle MakeMsg(clsScrollWin, 13) 



typedef struct SCROLL_WIN_STYLE { 



U16 vert Scrollbar 


1, 


horizScrollbar 


1, 


aut oVe rtScrollbar 


1, 


autoHorizScrollbar 


1, 


maskScrollbars 


1, 


expandChildWidth 

expandChildHeight 

contractChildWidth 


1, 
1, 
1, 


contract ChildHeight 

getDelta 

getSize 


1, 
1, 
1, 



// vertical scrollbar on/off 

// horizontal scrollbar on/off 

// vert scrollbar on/off based on clientWin 

// horiz scrollbar on/off based on clientWin 

// mask out vert Scrollbar and horizScrollbar 

// expand the child's width to avail width 

// expand the child's height to avail height 

// contract the child's width to avail width 

// contract the child' s height to avail height 

// send msgScrollWinProvideDelta to client 

// send msgScrollWinProvideSize 
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wideVertScrollbar 
wideHorizScrollbar 
forward 
maskAll 
U16 xAlignment 
yAlignment 
vertClient 
horizClient 
xAlignRigorous 
yAlignRigorous 
private 1 

sparel : 

U16 spare2 : 

} SCROLL WIN STYLE, *P SCROLL 



2, 



1, 
1, 
1, 



1, // make the vertical scrollbar wide 

1, // make the horizontal scrollbar wide 

2, // what to forward from margins to clientWin 
1; // mask out maskScrollbars 

// x Alignment if innerWin wider than clientWin 
2, II y Alignment if innerWin taller than clientWin 
2, // choice of vertical sb client 
2, // choice of horizontal sb client 

// use xAlignment continuously 

// use yAlignment continuously 
// private 

5; // unused (reserved) 
16; // unused (reserved) 
WIN STYLE; 



rgtimenfs 



msgScrollWInSetStyle 

Sets the style values. 

Takes P_SCROLL_WIN_STYLE, returns STATUS. 

♦define msgScrollWinSetStyle MakeMsg(clsScrollWin, 14) 

typedef struct SCROLL WIN STYLE { 



U16 vertScrollbar 
horizScrollbar 
autoVertScrollbar 
autoHorizScrollbar 
maskScrollbars 
expandChildWidth 
expandChildHeight 
contract ChildWidth 
contractChildHeight 
getDelta 
getSize 

wideVertScrollbar 
wideHorizScrollbar 
forward 
maskAll 

U16 xAlignment 

yAlignment 

vertClient 

horizClient 

xAlignRigorous 

yAlignRigorous 

private 1 

sparel : 

U16 spare2 : 

} SCROLL WIN STYLE, *P SCROLL 



2, 



1, 
1, 
1, 



1, // vertical scrollbar on/off 
1, // horizontal scrollbar on/off 
1, // vert scrollbar on/off based on clientWin 
1, // horiz scrollbar on/off based on clientWin 
1, // mask out vertScrollbar and horizScrollbar 
1, // expand the child's width to avail width 
1, // expand the child's height to avail height 
1, // contract the child's width to avail width 
1, // contract the child's height to avail height 
1, // send msgScrollWinProvideDelta to client 
1, // send msgScrollWinProvideSize 
1, // make the vertical scrollbar wide 

1, // make the horizontal scrollbar wide 

2, // what to forward from margins to clientWin 
1; // mask out maskScrollbars 

// x Alignment if innerWin wider than clientWin 
2, // y Alignment if innerWin taller than clientWin 
2, // choice of vertical sb client 
2, // choice of horizontal sb client 

// use xAlignment continuously 

// use yAlignment continuously 
// private 

5; // unused (reserved) 
16; // unused (reserved) 
WIN STYLE; 



Comments 



The scrollWin self-sends msgWinSetLayoutDirty(true). It is the callers responsibility to re-layout the 
scrollWin. 



msgScroirWinGetMetrics 



Passes back the metrics. 

Takes P_SCROLL_WIN_METRICS, returns STATUS. 

tdefine msgScrollWinGetMetrics MakeMsg(clsScrollWin, 1) 



Message 
Arguments 
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Message typedef struct SCROLL_WIN_METRICS { 

Arguments SCROLL_WIN_STYLE style; // style bits 

OBJECT client; // for msgScrollWinProvideDelta 

WIN clientWin; // current window to scroll 

U16 colDelta, rowDelta; // metrics in device units 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} SCROLL WIN METRICS, *P SCROLL WIN METRICS; 



msgScrollWinSetMetrics 



Sets the metrics. 

Takes P_SCROLL_WIN_METRICS, returns STATUS. 

tdefine msgScrollWinSetMetrics MakeMsg(clsScrollWin, 2) 



typedef struct SCROLL_WIN_METRICS { 
SCROLL_WIN_STYLE style; 
OBJECT 
WIN 
U16 
U32 
U32 



// style bits 
client; // for msgScrollWinProvideDelta 

clientWin; // current window to scroll 
colDelta, rowDelta; // metrics in device units 
sparel; // unused (reserved) 

spare2; // unused (reserved) 



SCROLL WIN METRICS, *P SCROLL WIN METRICS; 



Comments 



msgScrollWinGetClientWin 

Passes back the current clientWin. 

Takes P_WIN, returns STATUS. 

#define msgScrollWinGetClientWin MakeMsg(clsScrollWin, 3) 

The current clientWin is the last window to be shown using msgScrollWinShowClientWin. 

msgScrollWinShowClientWin 

Sets the current clientWin; the specified window is be made visible. 

Takes WIN, returns STATUS. 

tdefine msgScrollWinShowClientWin MakeMsg(clsScrollWin, 4) 

If P_ARGS is not a child of the scrollWin's inner window, msgScrollWinAddClientWin is self-sent 
followed by msgWinLayout. 



msgScrollWinAddClientWin 

Adds another clientWin, inserting the specified window as a child of the scrollWin's inner window. 
Takes WIN, returns STATUS. 

♦define msgScrollWinAddClientWin MakeMsg(clsScrollWin, 11) 
Comments The specified window is set to be invisible (window flag wsVisible off). 



msgScrollWinRemoveClientWin 

Extracts the specified child window from the scrollWin. 

Takes WIN, returns STATUS. 

tdefine msgScrollWinRemoveClientWin MakeMsg(clsScrollWin, 12) 
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msgScrollWinGetVertScrollbar 

Passes back the vertical scrollbar. 

Takes P_WIN, returns STATUS. 

tdefine msgScrollWinGetVertScrollbar MakeMsg(clsScrollWin, 6) 



msgScrollWinGetHorizScrollbar 

Passes back the horizontal scrollbar. 

Takes P_WIN, returns STATUS. 

#define msgScrollWinGetHorizScrollbar MakeMsg(clsScrollWin, 7) 

msgScrollWinGetlnnerWin 

Passes back the inner window of the scrollWin. 

Takes P_WIN, returns STATUS. 

tdefine msgScrollWinGetlnnerWin MakeMsg(clsScrollWin, 9) 

msgScrollWinProvideDelta 

Self-sent when style.getDelta is set to true so that descendant or client can normalize the scroll if 
desired. 

Takes P_SCROLL_WIN_DELTA, returns STATUS. Category: descendant/client responsibility. 

#define msgScrollWinProvideDelta MakeMsg(clsScrollWin, 5) 

ige typedef struct SCROLL_WIN_DELTA { 

«enfs SCROLL_WIN scrollWin; // in: requesting scroll win 

// in: action to resolve 
// in: current or new offset 
// in/out: viewable portion of clientWin 
// in: line coordinate, if any 
// unused (reserved) 
} SCROLL_WIN_DELTA, *P_SCROLL_WIN_DELTA; 

Comments clsScrolfWIn responds by forwarding this message to the current clientWin. If you receive this message, 

you can send msgScroUWinGetDefaultPelta to pArgs->scrollWin to fill out pArgs with the default 
scrollWin response. 

msgScrollWinProvideSize 

Self-sent to determine bubble location and size. 

Takes P_SCROLL_WIN_SIZE, returns STATUS. Category: descendant/client responsibility. 

#define msgScrollWinProvideSize MakeMsg(clsScrollWin, 10) 

Arguments typedef struct SCROLL_WIN_SIZE { 

SCROLL_WIN scrollWin; // in: requesting scroll win 

SIZE32 viewSize; // out: desired view size (device units) 

SIZE32 docSize; // out: logical doc size (device units) 

U32 spare; // unused (reserved) 

} SCROLL_WIN_SIZE, *P_SCROLL_WIN_SIZE; 

Comments clsScrollWin responds by forwarding to the current clientWin (if style.getSize is true), or sending 

msgWinGetDesiredSize to the current clientWin (if style.getSize is false). In the latter case if there is no 
current clientWin, clsScrollWin uses for docSize. 



SCROLL 


WIN 


scrollWin; 


SCROLLBAR ACTION 


action; 


S32 




offset; 


RECT32 




viewRect; 


S32 




lineCoord; 


U32 




spare; 
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A clientWin responding to msgScrollWinProvideSize should fill out pArgs->viewSize and 
pArgs->docSize. 

msgScrollWinCheckScrollbars 

Determines whether the on/off state of either scrollbar needs to change and passes back the result. 

Takes P_BOOLEAN, returns STATUS. 

tdefine msgScrollWinCheckScrollbars MakeMsg(clsScrollWin, 15) 

Comments Clients wishing to fix up the states should dirty the layout of the scrollWin and then send 

msgWinLayout. O 

msgScrollWinAlign 

Sent to client when style.xAlignment or style.yAlignment is swAlignSelf. 

Takes P_SCROLL_WIN_ALIGN, returns STATUS. Category: client responsibility. 

♦define msgScrollWinAlign MakeMsg (clsScrollWin, 16) 

Arguments typedef struct SCROLL_WIN_ALIGN { 

SCROLL_WIN scrollWin; // in: requesting scroll win 

BOOLEAN alignX; // in: x dimension (false for y) 

RECT32 innerRect; // in/out: rect of innerWin, device units 

RECT32 clientRect; // in/out: rect of clientWin, device units 

U32 spare; // unused (reserved) 

} SCROLL_WIN_ALIGN, *P_SCROLL_WIN_ALIGN; 

Comments clsScrollWin sends this message to the scrolTWin's client or clientWin if the client is objNull. This 

message is sent when the child window changes size or the scrollWin inner window changes size. See the 
comment after "Default SCROLL_WIN_STYLE" for a further description of alignment. 

msgScrollWinGetDefaultDelta 

Compute the default response to msgScrollWinProvideDelta. 

Takes P_SCROLL_WIN_DELTA, returns STATUS. 

tdefine msgScrollWinGetDefaultDelta MakeMsg (clsScrollWin, 17) 

Message typedef struct SCROLL_WIN_DELTA { 

Arguments SCROLL_WIN scrollWin; // in: requesting scroll win 

SCROLLBAR_ACTION action; // in: action to resolve 

S32 offset; // in: current or new offset 

RECT32 viewRect; // in/out: viewable portion of clientWin 

S32 lineCoord; // in: line coordinate, if any 

U32 spare; // unused (reserved) 

} SCROLL_WIN_DELTA, *P_SCROLL_WIN_DELTA; 

Comments You can send this message to a scrollWin to compute the default scroll values for a given scrolling 

action. 

See Also msgScrollWinProvideDelta 

msgScrollWinRefreshSize 

Informs the receiver that msgScrollWinProvideSize would now return different size. 

Takes P_SIZE32, returns STATUS. 

tdefine msgScrollWinRefreshSize MakeMsg (clsScrollWin, 18) 
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Comments A client would send this to a scrollWin when the scrollWin has style.getSize set true and the client 

would now return different size in response to msgScrollWinProvideSize. The client passes the current 
size, and the scrollWin sends msgScrollWinProvideSize to the client (or the clientWin if that's null), 
then adjust the positions as if the clientWin had changed size. 

clsScrollWin just returns stsOK if style.getSize is false. 



P" Messages from other classes 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments clsScrollWin responds by filing away all its state, including any child windows that have wsSendFile 

turned on (wsSendFile is the default for clsBorder and its descendents). 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsScrollWin responds by restoring all of its state, including the child windows that were filed with the 

last msgSave. 

msgWinLayoutSelf 

Tell a window to layout its children. 

Takes P_WIN_METRICS, returns STATUS. 

Comments The scrollWin first gets the dimensions of its current clientWin by using msgWinGetDesiredSize. If 

there is no current clientWin, the scrollWin uses a width and height of in its computations. 

If the scrollWin did not shrinkwrap around the current clientWin, then the expandChild* and 
contractChild* styles come into play. If the clientWin's width is less than the width of the scrollWin s 
inner window (a direct child of the scrollWin that serves as a clipping window) and expandChildWidth 
is true, then the clientWin's width is expanded to fit. If the clientWin's width is greater than the inner 
window's and contractChildWidth is true, then the clientWin's width is reduced to fit. These rules hold 
for the height as well. 

Finally, if the clientWin's (possibly modified) width is still less than the inner window's, then the 
xAlignment style is used to place the clientWin within the inner window. This is also done in the 
vertical direction using yAlignment. 

The scrollWin adds or remove a vertical scrollBar as necessary if style.autoVertScrollbar is on, and the 
same is done for the horizontal direction (when both style.maskScrollbars and style.maskAll are off). 



msgWinSetFlags 

Sets the window flags. 

Takes P_WIN_METRIGS, returns STATUS. 

Comments clsScrollWin responds by first propagating the shrinkwrap values to the inner window, then calling its 

ancestor. 
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msgWinSend 

Sends a message up a window ancestry chain. 

Takes WIN_SEND, returns STATUS. 

Comments clsScrollWin responds by checking to see if pArgs->msg is msgScrollbarUpdate. If so, the scrollWin 

sends msgScrollbarUpdate to both of its scrollbars and then return stsOK. If not, then the scrollWin 
just calls its ancestor. 



msgGWinGesture 

Self-sent to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

omments If there is a current clientWin and style.forward is swForwardGesture, then the pArgs are transformed 

to the clientWin, and the clientWin is sent msgGWinGesture. The scrollWin returns the resulting 
status to the caller. 

Otherwise, the scrollWin compares the pArgs->msg with the state of the corresponding scrollbar. If the 
message is not a scrolling gesture, then the scrollWin returns stsMessagelgnored. If it is a vertical 
scrolling gesture and the vertical scrollbar is not active, then the scrollWin returns stsOK. Finally, if the 
message is a vertical scrolling gesture and the vertical scrollbar is active, the scrollWin transforms the 
pArgs to the scrollbar's space and return the result of sending msgGWinGesture to the scrollbar (unless 
the msgGWinGesture originated with the scrollbar, i.e. pArgs->uid == the scrollbar ~ in this case the 
scrollWin returns stsMessagelgnored). This processing is also done for horizontal scrolling gestures and 
the horizontal scrollbar. 

The above processing also is done whenever the scrollWin s inner window receives msgGWinGesture. 

Bfum Voloe stsOK a scrolling gesture would have had to be sent to an inactive scrollbar. 

stsMessagelgnored not a scrolling gesture, or message originated with the scrollbar to which 
msgGWinGesture would be sent. 

msgGWinForwardedGesture 

Message recieved when object is forwarded a gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

smmentts The scrollWin compares the pArgs->msg with the state of the corresponding scrollbar. If the message is 

not a scrolling gesture, then the scrollWin returns stsMessagelgnored. If it is a vertical scrolling gesture 
and the vertical scrollbar is not active, then the scrollWin returns stsOK. Finally, if the message is a 
vertical scrolling gesture and the vertical scrollbar is active, the scrollWin transforms the pArgs to the 
scrollbar's space and return the result of sending msgGWinGesture to the scrollbar (unless the 
msgGWinGesture originated with the scrollbar, i.e. pArgs->uid == the scrollbar ~ in this case the 
scrollWin returns stsMessagelgnored). This processing is also done for horizontal scrolling gestures and 
the horizontal scrollbar. 

The above processing also is done whenever the scrollWin's inner window receives msgGWinGesture. 

stwrn value stsOK a scrolling gesture would have had to be sent to an inactive scrollbar. 

stsMessagelgnored not a scrolling gesture, or message originated with the scrollbar to which 
msgGWinGesture would be sent. 



570 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



msgGWinXList 

Call back to announce gesture translation completed. 

Takes P_XLIST, returns STATUS. 

Comments If there is no current clientWin, or style. forward is not swForwardXList, then the scrollWin just calls its 

ancestor. 

Otherwise, the scrollWin transforms the pArgs to the clientWin and return the result of sending 
msgGWinXList to the clientWin. 

The above processing also is done whenever the scrollWin s inner window receives msgGWinXList. 

msgScrollbarVertScroll 

Client should perform vertical scroll. 

Takes P_SCROLLBAR_SCROLL, returns STATUS. Category: client responsibility. 

Comments Responding to this message is one of the key functions that scrollWins provide. Since the default 

scrollWin style.vertClient and .horizClient are both swClientScrollWin, it is usually the case that the 
scrollbars send their scrolling messages to the scrollWin. 

If there is no current clientWin, or the pArgs->action is sbEndScroll, the scrollWin just returns stsOK. 

If style.getDelta is true, the scrollWin sends msgScrollWinProvideDelta to the client (if that is 
non-null) or the clientWin (if the client was null). Otherwise, the scrollWin uses metrics.rowDelta for 
the sbLine* actions, and the inner windows height - metrics.rowDelta for the sbPage* actions. 

Once the scrollWin has determined the amount to scroll, it sends msgWinDelta to the clientWin. 
msgScrollbarHorizScroll 

Client should perform horizontal scroll. 

Takes P_SCROLLBAR_SCROLL, returns STATUS. Category: client responsibility. 

Comments Responding to this message is one of the key functions that scrollWins provide. Since the default 

scrollWin style.vertClient and .horizClient are both swClientScrollWin, it is usually the case that the 
scrollbars send their scrolling messages to the scrollWin. 

If there is no current clientWin, or the pArgs->action is sbEndScroll, the scrollWin just returns stsOK. 

If style.getDelta is true, the scrollWin sends msgScrollWinProvideDelta to the client (if that is 
non-null) or the clientWin (if the client was null). Otherwise, the scrollWin uses metrics.colDelta for 
the sbLine* actions, and the inner window's width - metrics.colDelta for the sbPage* actions. 

Once the scrollWin has determined the amount to scroll, it sends msgWinDelta to the clientWin. 



s omf«etits 



msgScrollbarProvideVertlnfo 

Client should provide the document and view info. 

Takes P_SCROLLBAR_PROVIDE, returns STATUS. Category: client responsibility. 

clsScrollWin responds by filling out the pArgs fields. It sets the viewLength to the height of the inner 
window. If there is a current clientWin, then the scrollWin sets the docLength to the height of the 
clientWin, and the offset to the difference between the top of the clientWin and the top of the inner 
window. If there is no current clientWin, the scrollWin sets both docLength and offset to 0. 
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msgScrollbarProvideHorizInfo 

Client should provide the document and view info. 

Takes P_SCROLLBAR_PROVIDE, returns STATUS. Category: client responsibility. 

Comments clsScrollWin responds by filling out the pArgs fields. It sets the viewLength to the width of the inner 

window. If there is a current clientWin, then the scrollWin sets the docLength to the width of the 
clientWin, and the offset to the negative of the clientWin's x. If there is no current clientWin, the 
scrollWin sets both docLength and offset to 0. 

msgEmbeddedWinShowChild o 

Display a given area of an embeddedWin to the user 

Takes P_EMBEDDED_WIN_SHOW_CHILD, returns STATUS. 

Comments clsScrollWin responds by sending messages to the vertical and/or horizontal scrollbars to scroll the client 

window area into view. 
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TABBAR.H 



This file contains the API definition for clsTabBar. 

clsTabBar inherits from clsTkTable. 

Implements a window that lays out its children in a single column or row. 

TabBars are most often seen at the side of Notebooks. clsTabBar will overlap its children in a regular 

fashion if they won't fit in the long dimension. clsTabBar also handles flick gestures forwarded to it by 

rearranging the children. 



Debugging Flags 

The clsTabBar debugging flag is 'K\ Defined values are: 
flagl 2 (Oxl 000) general debug info 



#ifndef TABBAR_INCLUDED 
#define TABBAR_INCLUDED 

#include <tktable . h> 



#ifndef TKTABLE_INCLUDED 
#endif 



Common #defines and typedefs 

typedef OBJECT TAB_BAR, *P_TAB_BAR; 



Direction 



#define tbDirectionVertical 
tdefine tbDirectionHorizontal 1 
typedef struct TAB_BAR_STYLE { 
U16 direction : 1, 

incrementalLayout : 1 , 

spare : 14; 

} TAB_BAR_STYLE, *P_TAB_BAR_STYLE; 

Default TabBar style: 

direction = tbDirectionVertical 
incrementalLayout = true 



// vertical tab bar 
// horizontal tab bar 

// vertical or horizontal 

// careful about add and remove children 

// unused (reserved) 



Messages 



msgNew 

Creates a tabBar window. 

Takes P_TAB_BAR_NEW, returns STATUS. Category: class message. 
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Arguments typedef Struct TAB_BAR_NEW_ONLY { 

TAB_BAR_STYLE style; // overall style 

U32 spare; // unused (reserved) 

} TAB_BAR_NEW_ONLY, *P_TAB_BAR_NEW_ONLY; 

#define tabBarNewFields \ 

tkTableNewFields \ 

TAB_BAR_NEW_ONLY tabBar; 

typedef struct TAB_BAR_NEW { 

tabBarNewFields 
} TAB_BAR_NEW, *P_TAB_BAR_NEW; 

Comment's The fields you commonly set are: 

pArgs->tabBar.style.direction whether horizontal or vertical 



msgNewDefaults 

Initializes the TAB_BAR_NEW structure to default values. 

Takes P_TAB_BAR_NEW, returns STATUS. Category: class message. 

age typedef struct TAB_BAR_NEW { 

«erits tabBarNewFields 

} TAB_BAR_NEW, *P_TAB_BAR_NEW; 

tents Zeroes out pArgs->tabBar and sets 

pArgs->win. flags. style |= wsTransparent | wsClipChildren; 
pArgs->win. flags. input |= inputDisable | inputTransparent ; 

pArgs->gWin. style. gestureEnable = false; 

pArgs->border.style.backgroundInk |= bsInkExclusive; 
pArgs->border. style. leftMargin = bsMarginNone; 
pArgs->border. style. rightMargin = bsMarginNone; 
pArgs->border. style. bottomMargin = bsMarginNone; 
pArgs->border. style. topMargin = bsMarginNone; 

pArgs->tableLayout. style. tblXAlignment = tlAlignCenter; 
pArgs->tableLayout. style. tblYAlignment = tlAlignCenter; 
pArgs->tableLayout. style. growChildHeight = false; 
pArgs->tableLayout. style. reverseY = true; 

pArgs->tableLayout.numCols. constraint = tlAbsolute; 
pArgs->tableLayout .numCols. value = 1; 
pArgs->tableLayout.numRows. constraint = tllnfinite; 
pArgs->tableLayout.colWidth. constraint = tlChildrenMax; 
pArgs->tableLayout . colWidth . gap = 0; 
pArgs->tableLayout.rowHeight. constraint = tlGroupMax; 
pArgs->tableLayout.rowHeight.gap = defaultRowGap; 

pArgs->tabBar. style. incrementalLayout = true; 

Also sets the default child structure in pArgs->tkTable.pButtonNew to be appropriate for labels and 
buttons that may be rotated 270 degrees and have curved overlapping "tabs". 

msgTabBarGetStyle 

Passes back the style values. 

Takes P_TAB_BAR_STYLE, returns STATUS. 

♦define msgTabBarGetStyle MakeMsg(clsTabBar, 1) 
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Message typedef struct TAB_BAR_STYLE { 
Arguments U16 direction : 1, 

incrementalLayout : 1 , 
spare : 14; 

} TAB BAR STYLE, *P TAB BAR STYLE; 



// vertical or horizontal 

// careful about add and remove children 

// unused (reserved) 



msgTabBarSetStyle 

Sets the style values. 

Takes P_TAB_BAR_STYLE, returns STATUS. 

#define msgTabBarSetStyle MakeMsg(clsTabBar, 2) 



Message 
Arguments 



typedef struct TAB_BAR_STYLE { 
U16 direction : 1, 
incrementalLayout : 1, 
spare : 14; 

} TAB BAR STYLE, *P TAB BAR STYLE; 



// vertical or horizontal 

// careful about add and remove children 

// unused (reserved) 



Messages from Other Classes 

tnsgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

clsTabBar responds by filing away its instance data. 



Comments 



Comments 



msgRestore 

Creates and restores an object from an object file. 
Takes P_OBJ_RESTORE, returns STATUS. 
clsTabBar responds by restoring its instance data. 

msgWinLayoutSelf 

Tells a window to layout its children. 

Takes P_WIN_METRICS, returns STATUS. 

When a tabBar receives msgWinLayoutSelf, it will ignore the current positions of its children and do a 
full relayout, crunching the children toward the bottom (right) of itself, if necessary. 

To insert or remove a child and cause the tabBar to incrementally fix up the tab positions (i.e., without 
doing a full relayout), use msgTkTableAdd* and msgTkTableRemove. When a tabBar receives these 
messages, it checks its incrementalLayout style bit. If this is on, the tabBar will fix up the area around 
the inserted/removed child. If the style bit is off, the tabBar will not do relayout. 

If you want to add/ remove more than a few tabs, turn incrementalLayout off, add/ remove the children, 
then send msgWinLayout to the tabBar. 

msgTkTableAdd* adds a child and will immediately fix up the layout of the tabBar s children (if 
style. incrementalLayout is true). 

msgTkTableRemove removes a child and will immediately fix up the layout of the tabBar 's children (if 
style.incrementalLayout is true). 



576 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 

msgWinSend 

Sends a message up a window ancestry chain. 

Takes P_WIN_SEND, returns STATUS. 

Comments When a tabBar receives this message, it is usually because the tabBar has an "expand" menu up, and the 

user has tapped on one of those menu buttons. 

If the pArgs->msg is not msgMenuDone, or the tabBar does not have a menu up, the tabBar will just 
return the result of calling its ancestor. 

Otherwise, the tabBar will take down the menu via msgMenuShow, post a msgDestroy to it, and then 
return stsOK. This is all the tabBar must do at this point, since the principle work of the menuButton 
was done when it sent its message to its client (in this case, the client is the tabBar). 

msgGWinForwardedGesture 

Message received when object is forwarded a gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

Comments TabBars respond to flick gestures by potentially altering the layout of their child windows. This allows a 

user to rearrange the child buttons when there's not enough room to display all the children fully. 

The tabBar will first test pArgs->msg to see if it is not a flick gesture or it is but it would have no 
meaning. If either is true, the tabBar will return stsMessagelgnored. 

If all the children are fully displayed, the tabBar will return stsOK. 

If style.direction is tbDirectionVertical and pArgs->msg is xgsFlickLeft, or the direction is 
tbDirectionHorizontal and pArgs->msg is xgsFlickUp, the tabBar will create and put up a menu over 
itself that looks like an expanded tabBar. The user then tap on one of the menu buttons; this will have 
the same effect as tapping on the corresponding tabBar child. After putting up the menu, the tabBar 
will return stsOK. 

If all of the above checks failed, the tabBar will process the flick gesture by moving its children as 
appropriate and then returning stsOK. 

msgTkTableChildDefaults 

Sets the defaults in P_ARGS for a common child. 

Takes P_UNKNOWN, returns STATUS. 

Here is how a tabBar processes this message if style.direction is tbDirectionVertical: 

pArgs->win. flags. style &= ~wsParentClip; 

pArgs->win. flags. style |= wsClipSiblings | wsClipChildren; 

if <pArgs->object .class inherits from clsBorder> { 

pArgs->border. style. edge = bsEdgeTop | bsEdgeRight | bsEdgeBottom; 

pArgs->border. style. join = bsJoinRound; 

pArgs->border.style.backgroundInk = bsInkWhite; 

pArgs->border . style . topMargin = bsMarginMedium; 

pArgs->border. style. bottomMargin = bsMarginMedium; 

pArgs->border. style. shadow = bsShadowThinBlack; 
} 
if <pArgs->object .class inherits from clsLabel> { 

pArgs->label. style. xAlignment = IsAlignCenter; 

pArgs->label. style. yAlignment = IsAlignCenter; 

pArgs->label. style. rotation = lsRotate270; 

pArgs->label. scale = IsScaleMedium; 
} 
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Here is how a tabBar processes this message if style.direction is tbDirectionHorizontal: 

pArgs->win. flags. style &= ~wsParentClip; 

pArgs->win. flags. style |= wsClipSiblings | wsClipChildren; 

if <pArgs->object. class inherits from clsBorder> { 

pArgs->border. style. edge = bsEdgeLeft | bsEdgeRight | bsEdgeBottom; 

pArgs->border. style. join = bsJoinRound; 

pArgs->border.style.backgroundInk = bsInkWhite; 

pArgs->border. style. leftMargin = bsMarginMedium; 

pArgs->border. style. rightMargin = bsMarginMedium; 

pArgs->border.style.topMargin = bsMarginSmall ; 

pArgs->border.style.bottomMargin = bsMarginSmall; 2 

pArgs->border. style. shadow = bsShadowThinBlack; O 

pArgs->border . style . shadowGap = bsGapNone; 2 

} 5 

if <pArgs->ob ject . class inherits from clsLabel> { ^ 

pArgs->label. style. xAlignment = IsAlignCenter; ^ H 

pArgs->label. style. yAlignment = IsAlignCenter; 

pArgs->label. style. rotation = IsRotateNone; 

pArgs->label . scale = IsScaleMedium; 
} 



msgTkTableAddAsFirst 

Adds specified window as the first child in the table. 

Takes WIN, returns STATUS. 

Comments clsTabBar responds by first calling its ancestor, then checking style. incrementalLayout. If this is false, 

the tabBar will just return stsOK. 

Otherwise, the tabBar will do whatever layout is necessary to fix up the positions of its children. 



msgTkTableAddAsLast 

Adds specified window as the last child in the table. 

Takes WIN, returns STATUS. 

Comments clsTabBar responds by first calling its ancestor, then checking style.incrementalLayout. If this is false, 

the tabBar will just return stsOK. 

Otherwise, the tabBar will do whatever layout is necessary to fix up the positions of its children. 

msgTkTableAddAsSibling 

Inserts specified window in front of or behind an existing child. 

Takes P_TK_TABLE_ADD_SIBLING, returns STATUS. 

Comments clsTabBar responds by first calling its ancestor, then checking style.incrementalLayout. If this is false, 

the tabBar will just return stsOK. 

Otherwise, the tabBar will do whatever layout is necessary to fix up the positions of its children. 
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msgTkTableAddAt 

Inserts specified window table at specified index. 

Takes P_TK_TABLE_ADD_AT, returns STATUS. 

:©mmenfs clsTabBar responds by first calling its ancestor, then checking style.incrementalLayout. If this is false, 

the tabBar will just return stsOK. 

Otherwise, the tabBar will do whatever layout is necessary to fix up the positions of its children. 

msgTkTableRemove 

Extracts specified window. 

Takes WIN, returns STATUS. 

:©mm®nts Currently, the tabBar just calls its ancestor and does not attempt to fix up the layout of its children. This 

may change in the future. 
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TBAR.H 



This file contains the API definition for clsTitleBar. 

clsTitleBar inherits from clsButton. 

Title bars are the standard frame decorations which support dragging a frame, bringing a frame to the 
front, and flicking to zoom. 



#ifndef TBARJENCLUDED 
tdefine TBAR_INCLUDED 

tinclude <button.h> 



#ifndef BUTTON_INCLUDED 
#endif 



Common #defines and fypedefs 

typedef OBJECT TITLE_BAR; 
typedef struct TITLE_BAR_STYLE { 

U16 spare : 16; // unused (reserved) 
} TITLE_BAR_STYLE, *P_TITLE_BAR_STYLE; 

Messages 



msgNew 

Creates a title bar window. 

Takes P_TITLE_BAR_NEW, returns STATUS. Category: class message. 

Arguments typedef struct TITLE_BAR_NEW_ONLY { 
TITLE_BAR_STYLE Style; 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} TITLE_BAR_NEW_ONLY, *P_TITLE_BAR_NEW_ONLY; 

tdefine titleBarNewFields \ 
buttonNewFields \ 
TITLE_BAR_NEW_ONLY titleBar; 

typedef struct TITLE_BAR_NEW { 

titleBarNewFields 
} TITLE BAR NEW, *P TITLE BAR NEW; 



ss0ge 
luniersfs 



msgNewDefaults 

Initializes the TITLE_BAR_NEW structure to default values. 

Takes P_TITLE_BAR_NEW, returns STATUS. Category: class message. 

typedef struct TITLE_BAR_NEW { 

titleBarNewFields 
} TITLE BAR NEW, *P TITLE BAR NEW; 
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ments Zeroes out pArgs->titleBar and sets 

pArgs->border . style . join = bs JoinSquare; 

pArgs->border. style. shadow = bsShadowNone; 

pArgs->border. style. leftMargin = bsMarginMedium; 

pArgs->border. style. rightMargin = bsMarginMedium; 

pArgs->border. style. bottomMargin = bsMarginSmall + bsMarginSmall; 

pArgs->border. style. topMargin = bsMarginMedium + bsMarginSmall; 

pArgs->border. style. drag = bsDragHoldDown; 

pArgs->border. style. top = bsTopUp; 
pArgs->border. style. getDeltaWin = true; 

pArgs->control. style. previewEnable = false; 

pArgs->label . style . xAlignment = IsAlignCustom; 

pArgs->button. style. feedback = bsFeedbackNone; 

msgTitleBarGetStyle 

Passes back the current style values. 

Takes P_TITLE_BAR_STYLE, returns STATUS. 

#define msgTitleBarGetStyle MakeMsg(clsTitleBar, 1) 

typedef Struct TTTLE_BAR_STYLE { 

U16 spare : 16; // unused (reserved) 

} TITLE_BAR_STYLE, *P_TITLE BAR STYLE; 

msgTitleBarSetStyle 

Sets the style values. 

Takes P_TITLE_BAR_STYLE, returns STATUS. 

#define msgTitleBarSetStyle MakeMsg(clsTitleBar, 2) 

«ge typedef struct TITLE_BAR_STYLE { 
menfs U16 spare : 16; // unused (reserved) 

} TITLE BAR STYLE, *P TITLE BAR STYLE; 
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TBUTTON.H 



This file contains the API definition for clsTabButton. 

clsTabButton inherits from clsButton. 

Provides a class of button useful in the popup choice contained in the title of option sheets, because tab 
buttons hold some flags, a window uid, and an extra client. 



tifndef TBUTTON_INCLUDED 
#define TBUTTON_INCLUDED 

tinclude <clsmgr.h> 
tinclude <button.h> 



tifndef CLSMGR_INCLUDED 

#endif 

tifndef BUTTON_INCLUDED 

tendif 



Common #defines and typedefs 

typedef struct TAB BUTTON METRICS { 



U16 flags; 

WIN win; 

OBJECT client; 

U32 clientData[2] 

U32 spare; 



// arbitrary flags 

// associated window uid 

// associated client 

// arbitrary client data 

// reserved 



} TAB BUTTON METRICS, *P TAB BUTTON METRICS; 



msgNew 

Creates a tab button. 

Takes P_TAB_BTJTTON_NEW, returns STATUS. Category: class message. 

Arguments typedef Struct TAB_BUTTON_NEW_ONLY { 

TAB_BUTTON_METRICS metrics; 
U32 spare; // reserved 

} TAB_BUTTON_NEW_ONLY, *P_TAB_BUTTON_NEW_ONLY; 

tdefine tabButtonNewFields \ 
buttonNewFields \ 

TAB_BUTTON_NEW_ONLY tabButton; 

typedef struct TAB_BUTTON_NEW { 

tabButtonNewFields 
} TAB_BUTTON_NEW, *P_TAB_BUTTON_NEW; 

Comments The fields you commonly set are: 

pArgs->tabButton.metrics.win a window uid to hold 
pArgs->tabButton.metrics.client a client uid to hold 
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msgNewDefaults 

Initializes the TAB_BUTTON_NEW structure to default values. 

Takes P_TAB_BUTTON_NEW, returns STATUS. Category: class message. 

typedef struct TAB_BUTTON_NEW { 

tabButtonNewFields 
} TAB BUTTON NEW, *P TAB BUTTON NEW; 



Comments Zeroes out pArgs->tabButton. 



msgTabButtonGetMetrics 

Passes back the metrics of a tab button. 

Takes P_TAB_BUTTON_METRICS, returns STATUS. 

tdefine msgTabButtonGetMetrics MakeMsg(clsTabButton, 1) 

typedef struct TAB_BUTTON_METRICS { 

U16 flags; // arbitrary flags 

WIN win; // associated window uid 

OBJECT client; // associated client 

U32 clientData[2] ; // arbitrary client data 

U32 spare; // reserved 

} TAB BUTTON METRICS, *P TAB BUTTON METRICS; 



msgTabButtonSetMetrics 

Sets the metrics of a tab button. 

Takes P_TAB_BUTTON_METRICS, returns STATUS. 

tdefine msgTabButtonSetMetrics MakeMsg(clsTabButton, 2) 

ftessoge typedef struct TAB_BUTTON_METRICS { 

Arguments U16 flags; // arbitrary flags 

WIN win; // associated window uid 

OBJECT client; // associated client 

U32 clientData[2] ; // arbitrary client data 

U32 spare; // reserved 

} TAB BUTTON METRICS, *P TAB BUTTON METRICS; 



msgTabButtonGetFlags 

Passes back the flags of a tab button. 

Takes P_U16, returns STATUS. 

tdefine msgTabButtonGetFlags MakeMsg(clsTabButton, 3) 



msgTabButtonSetFlags 

Sets the flags of a tab button. 

Takes U16, returns STATUS. 

tdefine msgTabButtonSetFlags MakeMsg(clsTabButton, 4) 



TBUTTON.H 583 

Messages from Other Classes 



Messages from Other Classes 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments clsTabButton will save its instance data. 

If the TAB_BUTTON_METRICS.win is not null and the windows wsSendFile flag is on, the window will 
be filed with msgResPutObject (the window's wsFilelnline flag is cleared first). 

If the TAB_BUTTON_METRICS.client is OSThisAppO, this fact is saved so that clsTabButton's response 
to msgRestore will restore the client to OSThisAppO again. If the client is not OSThisAppO, 
msgRestore will set the client to null. 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

Zomments clsTabButton restores its instance data. 

If the TAB_BUTTON_METRICS.client had been OSThisAppO at msgSave time, msgRestore will set the 
client to OSThisAppO again. 
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TKFIELD.H 



This file contains the API definitions for clsDateField, clsFixedField, clsIntegerField, and clsTextField. 

clsDateField inherits from clsField. 

Provides a field that treats its label string as a date. 

clsFixedField inherits from clsField. 

Provides a field that treats its label string as a number in hundredths. 

clsIntegerField inherits from clsField. 

Provides a field that treats its label string as an integer. 

clsTextField inherits from clsField. 

Provides a field that treats its label string as a string. 

These four classes are used mainly on option sheets. Because these subclasses provide a simple API and 
somewhat limited functionality, clients should consider subclassing clsField rather than these. 

♦ifndef TKFIELD_INCLUDED 
♦define TKFIELD INCLUDED 



♦include <clsmgr.h> 

♦include <field.h> 
♦include <time.h> 



♦ifndef CLSMGRJCNCLUDED 

♦endif 

♦ifndef FIELD_INCLUDED 

♦endif 



clsDateField 

This section describes the API for clsDateField. 

Debugging Flags 

The clsDateField debugging flag is 'K'. Defined values are: 
flagO (0x0001) general 



Common # defines and lypedefs 



♦define stsDateFieldEmpty 
♦define stsDateFieldlnvalid 
// Date Flags 

♦define dfsMonthName flagO 
♦define dfsFullName flagl 

typedef struct { 

U16 flags; 

U16 spare; 
} DATE FIELD STYLE, *P DATE FIELD STYLE; 



MakeStatus (clsDateField, 1) 
MakeStatus (clsDateField, 2) 
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Default DATE_FIELD_STYLE: 

flags = 
typedef struct tm TIME DESC, *P TIME DESC; 



Arguments 



Arguments 



Comments 



msgNew 

Creates a date field. 

Takes P_DATE_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct { 

DATE_FIELD_STYLE style; 

U32 spare; 

} DATE_FIELD_NEW_ONLY, *P_DATE_FIELD_NEW_ONLY; 

#define dateFieldNewFields \ 
fieldNewFields \ 

DATE_FIELD_NEW_ONLY dateField; 

typedef struct DATE_FIELD_NEW { 

dateFieldNewFields 
} DATE_FIELD_NEW, *P_DATE_FIELD_NEW; 

The fields you commonly set are: 
pArgs->dateField.style.flags appropriate flags 



msgNewDefaults 

Initializes the DATE_FIELD_NEW structure to default values. 

Takes P_DATE_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct DATE_FIELD_NEW { 

dateFieldNewFields 
} DATE_FIELD_NEW, *P_DATE_FIELD_NEW; 

Zeroes out pArgs->dateField and sets: 

pArgs->border. style. edge = bsEdgeNone; 
pArgs->border. style. border Ink = bsInkGray66; 
pArgs->field. style. editType = fstOverWrite; 



Message 
Arguments 



msgDateFieldGetStyle 

Passes back the receiver's style. 

Takes P_DATE_FIELD_STYLE, returns STATUS. 

#define msgDateFieldGetStyle MakeMsg(clsDateField, 1) 

typedef struct { 

U16 flags; 

U16 spare; 

} DATE_FIELD_STYLE, *P_DATE_FIELD_STYLE; 

msgDateFieldSetStyle 

Sets the receiver's style. 

Takes P_DATE_FIELD_STYLE, returns STATUS. 

♦define msgDateFieldSetStyle MakeMsg(clsDateField, 2) 

typedef struct { 

U16 flags; 

Ul 6 spare ; 
} DATE FIELD STYLE, *P DATE FIELD STYLE; 
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msgDateFieldGetValue 

Passes back the receiver's value in the time descriptor. 

Takes P_TIME_DESC, returns STATUS. 

tdefine msgDateFieldGetValue MakeMsg(clsDateField, 3) 

stsDateFieldEmpty field has no content (*pArgs not set). 

stsDateFieldlnvalid field's content unrecognized (*pArgs not set). 

msgDateFieldSetValue o 

Sets the receiver's label string from the time descriptor. 



Takes P_TIME_DESC, returns STATUS. 

tdefine msgDateFieldSetValue MakeMsg(clsDateField, 4) 

msgControlGetValue 

Passes back the receiver's value in YYYYMMDD format. 
Takes P_U32, returns STATUS. 
rm Value stsDateFieldEmpty field has no content (*pArgs not set). 

stsDateFieldlnvalid field's content unrecognized (*pArgs not set). 

msgControlSetValue 

Sets the receiver's label string from a U32 in YYYYMMDD format. 
Takes U32, returns STATUS. 

msgControlSetDirty 

Sets style.dirty. 

Takes BOOLEAN, returns STATUS. 

merits The date field will alter the ink of its bottom edge (if it has one) to bsInkBlack if dirty, bsInkGray66 if 

not. 

In PenPoint 1.0, clsDateField does not respond to msgControlSetStyle or msgControlSetMetrics to 
watch for the CONTROL_STYLE. enable bit changing. 

dsFixedField 

This section describes the API for dsFixedField. 

Common #defines and typedefs 

tdefine stsFixedFieldEmpty MakeStatus (dsFixedField, 1) 
tdefine stsFixedFieldlnvalid MakeStatus (dsFixedField, 2) 

typedef struct { 

U16 flags; 

U16 spare; 
} FIXED FIELD STYLE, *P FIXED FIELD STYLE; 
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msgNew 

Creates a fixed field. 

Takes P_FIXED_FIELD_NEW, returns STATUS. Category: class message. 

Arguments typedef struct { 

FIXED_FIELD_STYLE style; 

U32 spare; 

} FIXED_FIELD_NEW_ONLY, *P_FIXED_FIELD_NEW_ONLY; 

Idefine fixedFieldNewFields \ 
fieldNewFields \ 

FIXED_FIELD_NEW_ONLY fixedField; 

typedef struct FIXED_FIELD_NEW { 

fixedFieldNewFields 
} FIXED FIELD NEW, *P FIXED FIELD NEW; 



msgNewDefaults 

Initializes the FIXED_FIELD_NEW structure to default values. 

Takes P_FIXED_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct FIXED_FIELD_NEW { 

fixedFieldNewFields 
} FIXED_FIELD_NEW, *P_FIXED_FIELD_NEW; 

Zeroes out pArgs->fixedField and sets: 

pArgs->border. style. edge = bsEdgeNone; 
pArgs->border. style. borderlnk = bsInkGray66; 
pArgs->field. style. editType = fstOverWrite; 
pArgs->field. style. noSpace = true; 
pArgs->field. style. veto = true; 



msgFixedFieldGetStyle 

Passes back the receiver's style. 

Takes P_FIXED_FIELD_STYLE, returns STATUS. 

#define msgFixedFieldGetStyle MakeMsg (clsFixedField, 1) 

typedef struct { 

U16 flags; 

U16 spare; 
} FIXED FIELD STYLE, *P FIXED FIELD STYLE; 



msgFixedFieldSetStyle 

Sets the receiver's style. 

Takes P_FIXED_FIELD_STYLE, returns STATUS. 

#define msgFixedFieldSetStyle MakeMsg (clsFixedField, 2) 

typedef struct { 

U16 flags; 

U16 spare; 
} FIXED FIELD STYLE, *P FIXED FIELD STYLE; 
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msgControlGetValue 

Get the receiver's value as an S32 in hundredths. 

Takes P_S32, returns STATUS. 

stsFixedFieldEmpty field has no content (*pArgs not set). 

stsFixedFieldlnvalid field's content unrecognized (*pArgs not set). 



msgControlSetValue 

Sets the receiver's label strin 
Takes S32, returns STATUS. 



Sets the receiver's label string from a S32 in hundredths. O 

° O 



msgControlSetDirty 

Sets style.dirty. 

Takes BOOLEAN, returns STATUS. 

ments The fixed field will alter the ink of its bottom edge (if it has one) to bsInkBlack if dirty, bsInkGray66 if 

not. 

In PenPoint 1.0, clsFixedField does not respond to msgControlSetStyle or msgControlSetMetrics to 
watch for the CONTROL_STYLE. enable bit changing. 

dslntegerField 

This section describes the API for dslntegerField. 

Common #defines and typedefs 

#define stsIntegerFieldEmpty MakeStatus (dslntegerField, 1) 
#define stsIntegerFieldlnvalid MakeStatus (dslntegerField, 2) 
typedef struct { 

U16 flags; 

U16 spare; 
} INTEGER FIELD STYLE, *P INTEGER FIELD STYLE; 



msgNew 

Creates an integer field. 

Takes P_INTEGER_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct { 

INTEGER_FIELD_STYLE style; 

U32 spare; 

} INTEGER_FIELD_NEW_ONLY, *P_INTEGER_FIELD_NEW_ONLY; 

#define integerFieldNewFields \ 
fieldNewFields \ 

INTEGER_FIELD_NEW_ONLY integerField; 

typedef struct INTEGER_FIELD_NEW { 

integerFieldNewFields 
} INTEGER FIELD NEW, *P INTEGER FIELD NEW; 



590 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



msgNewDefaults 

Initializes the INTEGER_FIELD_NEW structure to default values. 

Takes P_INTEGER_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct INTEGER_FIELD_NEW { 

integerFieldNewFields 
} INTEGER_FIELD_NEW, *P_INTEGER_FIELD_NEW; 

Zeroes out pArgs->integerField and sets: 

pArgs->border. style. edge = bsEdgeNone; 
pArgs->border. style. borderlnk = bsInkGray66; 
pArgs->field. style. edit Type = fstOverWrite; 
pArgs->field. style. noSpace = true; 
pArgs->field. style. veto = true; 

msglntegerFieldGetStyle 

Passes back the receiver's style. 

Takes P_INTEGER_FIELD_STYLE, returns STATUS. 

#define msglntegerFieldGetStyle MakeMsg(clsIntegerField, 1) 

typedef struct { 

U16 flags; 

U16 spare; 
} INTEGER_FIELD_STYLE, *P_INTEGER_FIELD_STYLE; 

msglntegerFieldSetStyle 

Sets the receiver's style. 

Takes P_INTEGER_FIELD_STYLE, returns STATUS. 

#define msglntegerFieldSetStyle MakeMsg(clsIntegerField, 2) 

typedef struct { 

U16 flags; 

U16 spare; 
} INTEGER_FIELD_STYLE, *P_INTEGER_FIELD_STYLE; 

msgControlGetValue 

Passes back the receiver's value as an S32. 
Takes P_S32, returns STATUS. 
Return Vol«e stsIntegerFieldEmpty field has no content (*pArgs not set). 

stsIntegerFieldlnvalid field's content unrecognized (*pArgs not set). 



msgControlSetValue 

Sets the receiver's label string from a S32. 
Takes S32, returns STATUS. 
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cIsTextField 



msgControlSetDirty 

Sets style/dirty. 

Takes BOOLEAN, returns STATUS. 

Comments The integer field will alter the ink of its bottom edge (if it has one) to bsInkBlack if dirty, bsInkGray66 

if not. 

In PenPoint 1.0, clsIntegerField does not respond to msgControlSetStyle or msgControlSetMetrics to 
watch for the CONTROL_STYLE.enable bit changing. 

f cIsTextField 

This section describes the API for cIsTextField. 

Pjr Common #defines and typedefs 

typedef struct { 

U16 flags; 

U16 spare; 
} TEXT_FIELD_STYLE, *P_TEXT_FIELD_STYLE; 

msgNew 

Creates a text field. 

Takes P_TEXT_FIELD_NEW, returns STATUS. Category: class message. 

Arguments typedef struct { 

TEXT_FIELD_STYLE style; 

U32 spare; 

} TEXT_FIELD_NEW_ONLY, *P_TEXT_FIELD_NEW_ONLY; 

tdefine textFieldNewFields \ 
fieldNewFields \ 

TEXT_FIELD_NEW_ONLY textField; 

typedef struct TEXT_FIELD_NEW { 

textFieldNewFields 
} TEXT FIELD NEW, *P TEXT FIELD NEW; 



msgNewDefaults 

Initializes the TEXT_FIELD_NEW structure to default values. 

Takes P_TEXT_FIELD_NEW, returns STATUS. Category: class message. 

typedef struct TEXT_FIELD_NEW { 
s textFieldNewFields 

} TEXT_FIELD_NEW, *P_TEXT_FIELD_NEW; 

Comments Zeroes out pArgs->textField and sets: 

pArgs->border. style. edge = bsEdgeBottom; 
pArgs->border. style. border Ink = bsInkGray66; 



msgTextFieldGetStyle 

Passes back the receiver's style. 

Takes P_TEXT_FIELD_STYLE, returns STATUS. 

#define msgTextFieldGetStyle MakeMsg (cIsTextField, 1) 
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Message typedef struct { 

Arguments U16 flags; 

U16 spare; 

} TEXT_FIELD_STYLE, *P_TEXT_FIELD_STYLE; 

msgTextFieldSetStyle 

Sets the receiver's style. 

Takes P_TEXT_FIELD_STYLE, returns STATUS. 

tdefine msgTextFieldSetStyle MakeMsg(clsTextField, 2) 

Vlessage typedef struct { 

Arguments U16 flags; 

U16 spare; 

} TEXT_FIELD_STYLE, *P_TEXT_FIELD_STYLE; 

msgControlSetDirty 

Sets style. dirty. 

Takes BOOLEAN, returns STATUS. 

Jommenrs The text field will alter the ink of its bottom edge (if it has one) to bsInkBlack if dirty, bsInkGray66 if 

not. 

In PenPoint 1.0, clsTextField does not respond to msgControlSetStyle or msgControlSetMetrics to 
watch for the CONTROL_STYLE. enable bit changing. 
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TKTABLE.H 



This file contains the API definition for clsTkTable. 
clsTkTable inherits from clsTableLayout. 

Toolkit tables support complex nested arrangements of buttons, labels, and even other toolkit tables. 

Pfr Debugging Flags 

The clsTkTable debugging flag is 'K\ Defined values are: 
flagl2 (0x1000) general debug info 



#ifndef TKTABLE_INCLUDED 
#define TKTABLE_INCLUDED 

♦include <ostypes.h> 
#include <t layout. h> 
#include <button.h> 



#ifndef OSTYPES_INCLUDED 

#endif 

♦ifndef TLAYOUT_INCLUDED 

#endif 

tifndef BUTTON_INCLUDED 

#endif 



Common #defines and typedefs 

typedef OBJECT TK_TABLE; 
typedef struct TK_TABLE_STYLE { 

U16 spare : 16; // unused (reserved) 
} TK TABLE STYLE, *P TK TABLE STYLE; 



TK_TABLE_ENTRY Flags 



♦define tkLabelEntry 
#define tkLabelStringld 
♦define tkPNew 

#define tkLabelBold 
♦define tkLabel Wordwrap 

♦define tkButtonPargsValue 
♦define tkButtonPargsUID 
♦define tkButtonOn 
♦define tkButtonHalfHeight 
♦define tkButtonManagerNone 
♦define tkButtonToggle 
♦define tkButtonBox 

♦define tkMenuPullRight 
♦define tkMenuPullDown 

♦define tkContentsSection 

♦define tklnputDisable 

♦define tkBorderEdgeTop 
♦define tkBorderEdgeBottom 
♦define tkBorderMarginNone 
♦define tkBorderLooklnactive 



(U32)flag2) 

(U32)flagl4) 

(U32)flag4) 

(U32)flag3) 

(U32)flag25) 

(U32)flag5) 

(U32)flag6) 

(U32)flag7) 

(U32)flagl9) 

(U32)flag20) 

(U32)flag8) 

(U32)flagl) 

(U32)flag9) 

(U32)flagl0) 

(U32)flag9) 

(U32)flag21) 

(U32)flagll) 
(U32)flagl2) 
(U32)flag22) 
(U32)flagl3) 



// argl is a P_TK_TABLE_ENTRY 

// argl is a string resid 

// argl is a pNew 

// use a bold system font 

// word-wrap the label string 

// send value instead of Data 

// send UID instead of Data 

// turn on the button 

// use half -height button border 

// set button manager to bsManagerNone 

// make button a toggle 

// use bsFeedbackBox 

// arg2 is pEntries for pull-right 

// arg2 is pEntries for pull-down 

// arg2 is pEntries for section contents 

// disable input 

// turn on top border 

// turn on bottom border 

// turn off all margins 

// make entry inactive 
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#define tkTableWideGap 

♦define tkTableHorizontal 

♦define tkTableVertical 

#define tkTableXAlignBaseline 

♦define tkTableYAlignBaseline 

♦define tkNoProto 
♦define tkNoClient 

♦define tkPopupChoiceFont 

♦define tkControlDynamicClient 

♦define tkControlDynamicObject 

♦define tkControlDynamicPargs 

♦define tkControlCallSel 

♦define tkControlSelLocal 

♦define tkMenuButtonGetMenu 
♦define tkMenuButtonEnableMenu 

// Available flags: flagl6, flag31 
typedef struct TK_TABLE ENTRY { 



P UNKNOWN 


argl ; 


U32 


arg2; 


U32 


arg3; 


U32 


tag; 


U32 


flags; 


CLASS 


childClass; 


U32 


helpld; 


U32 


spare ; 



( (U32) flagl5) // wide gap between col 1 & 2 

((U32)flagl7) // table is horizontal 

((U32)flag24) // table is vertical 

((U32)flag0) // childXAlignment = tlAlignBaseline 

((U32)flag27) // childYAlignment = tlAlignBaseline 

( (U32) flagl8) // don't use prototypical pButtonNew 

((U32)flag23) // don't copy client field 

( (U32) flag26) // use current font names 

((U32)flag0) // dynamicEnable = csDynamicClient 

( (U32) flag27) // dynamicEnable = csDynamicObject 

( (U32) flag28) // dynamicEnable = csDynamicPargs 
tkControlDynamicObject 
tkControlDynamicPargs 

( (U32) flag29) // send msgMenuButtonProvideMenu 

((U32)flag30) // send msgControlEnable 



// argument for class, e.g. pString 

// argument for class, e.g. msg 

// argument for class, e.g. data 

// window tag 

// e.g. tkLabelBold | tkButtonPargs 

// class to create or objNull for default 

// help id for clsGWin 

// unused (reserved) 



} TK_TABLE_ENTRY, *P_TK_TABLE_ENTRY; 

Interpretation of argl, arg2, and arg3 for different classes: 



clsLabel 

clsButton 

clsMenuButton 

clsMenuButt on 

clsContentsButton 

clsContentsButton 

clsTkTable 
clsChoice 



pString 

pString, 

pString, 

pString, 

pString, 

pString, 

pEntries, 
pEntries, 



clsToggleTable pEntries, 

clsPopupChoice pEntries, 

clsPopupChoice prune, 

clsField pString, 

clsListBox nEntries, 

clsFontListBox role, 



msg, data 
pEntries 
msg, data 
pEntries 
msg, data 

numRows/cols 
numRows/cols 
numRows/cols 
numRows/cols 
numRows/cols 

numCols, maxLen 
nEntriesToView 
nEntriesToView, look 



if (tkMenuPullRight | | tkMenuPullDown) 

if ! (tkMenuPullRight | | tkMenuPullDown) ) 

if (tkContentsSection) 

if ! (tkContentsSection) 



if (! tkPopupChoiceFont) 
if (tkPopupChoiceFont) 



Messages 



msgNew 

Creates a tk table window. 

Takes P_TK_TABLE_NEW, returns STATUS. Category: class message. 



typedef struct TK TABLE NEW ONLY { 



TK_TABLE_STYLE 


style; 


// 


OBJECT 


client; 


// 


P TK TABLE ENTRY 


pEntries; 


// 


U32 


spare4; 


// 


P BUTTON NEW 


pButtonNew; 


// 


U16 


spare3; 


// 


BUTTON_NEW 


buf; 


// 


OBJECT 


manager; 


// 


U32 


spare 1; 


// 


U32 


spare2 ; 


// 



overall style 

client for each button 

in/out: description for each child 

unused (reserved) 

default new struct 

unused (reserved) 

default storage 

manager to notify 

unused (reserved) 

unused (reserved) 



} TK TABLE NEW ONLY, *P TK TABLE NEW ONLY; 
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Common #defines and typedef* 

#define tkTableNewFields \ 

tableLayoutNewFields \ 

TK_TABLE_NEW_ONLY tkTable; 

typedef struct TK_TABLE_NEW { 

tkTableNewFields 
} TK_TABLE_NEW, *P_TK_TABLE_NEW; 

Comments clsTkTable will create and insert a child window for each entry in pArgs->tkTable.pEntries. 

After msgNew returns, pArgs->tkTable.pEntries will be left pointing to the null-terminating entry. 

Note that pArgs->tkTable.pEntries is used during msgNew only, and the original value can be freed (if 
allocated) after msgNew returns. 

For each entry, pArgs->pButtonNew will be used as the "prototypical" child new struct. The fields argl, 
arg2, arg3, tag, helpld and the semantics of each flag will be applied to the child new struct before 
creating the child. 

pArgs->client will be used to set the client for entries which inherit from clsTkTable, clsListBox, or 
clsControl, unless the tkNoClient flag is on for the entry. 

Before msgNew is sent to each child's class, msgTkTablelnit will be sent to the child's class with the 
following TK_TABLE_INIT parameters: 

pTkTableNew = pArgs; 

pChildNew = pointer to child's new struct; 

pEntry = pointer to child's TK_TABLE_ENTRY struct; 

This allows other classes to define mappings for TK_TABLE_ENTRY to child new structs. 

msgNewDefaults 

Initializes the TK_TABLE_NEW structure to default values. 

Takes P_TK_TABLE_NEW, returns STATUS. Category: class message. 

Message typedef Struct TK_TABLE_NEW { 

Arguments tkTableNewFields 

} TK_TABLE_NEW, *P_TK_TABLE_NEW; 

Comments Zeroes out pArgs-> tkTable and sets 

pArgs->tableLayout. style. growChildWidth = false; 
pArgs->tableLayout. style. growChildHeight = true; 

pArgs->tableLayout.numCols. constraint = tllnfinite; 
pArgs->tableLayout.numRows. constraint = tlAbsolute; 
pArgs->tableLayout.numRows. value = 1; 

pArgs->tableLayout.colWidth. constraint = tlGroupMax; 
pArgs->tableLayout.colWidth.gap = defaultColGap; 
pArgs->tableLayout .rowHeight . constraint = tlChildrenMax; 
pArgs->tableLayout.rowHeight.gap = de fault RowGap; 

// default is a table of regular buttons 
pArgs->tkTable.pButtonNew = &pArgs->tkTable.buf ; 

Sends msgNewDefaults(pArgs->tkTable.pButtonNew) to clsButton, then alters 
pArgs->tkTable.pButtonNew as described in msgTkTableChildDefaults. 
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msgTkTableGetStyle 

Passes back the current style values. 

Takes P_TK_TABLE_STYLE, returns STATUS. 

#define msgTkTableGetStyle MakeMsg (clsTkTable, 1) 

typedef struct TK_TABLE_STYLE { 

U16 spare : 16; // unused (reserved) 

} TK TABLE STYLE, *P TK TABLE STYLE; 



msgTkTableSetStyle 

Sets the style values. 

Takes P_TK_TABLE_STYLE, returns STATUS. 

♦define msgTkTableSetStyle MakeMsg(clsTkTable, 2) 

typedef struct TK_TABLE_STYLE { 

U16 spare : 16; // unused (reserved) 

} TK TABLE STYLE, *P TK TABLE STYLE; 



msgTkTableGetClient 

Passes back the client of the first child in the table. Note that the children may have been created with 
different clients. 

Takes P_UID, returns STATUS. 

#define msgTkTableGetClient MakeMsg(clsTkTable, 3) 

clsTkTable sends msgControlGetClient(pArgs) to the first (bottom-most) child to retrieve the client. 



msgTkTableSetClient 

Sets the client of each child in the table to pArgs. 

Takes UID, returns STATUS. 

♦define msgTkTableSetClient MakeMsg (clsTkTable, 4) 

clsTkTable sends msgControlSetClient(pArgs) to each child. 

msgTkTableGetManager 

Passes back the manager. 

Takes PJJID, returns STATUS. 

♦define msgTkTableGetManager MakeMsg (clsTkTable, 7) 

msgTkTableSetManager 

Sets the manager. 

Takes UID, returns STATUS. 

♦define msgTkTableSetManager MakeMsg (clsTkTable, 8) 
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Common #defines and typadefs 



msgTkTableGetMetrics 

Passes back the metrics. 

Takes P_TK_TABLE_METRICS, returns STATUS. 

#define msgTkTableGetMetrics MakeMsg (clsTkTable, 5) 

Arguments typedef struct TK_TABLE_METRICS { 

TK_TABLE_STYLE style; // overall style 

OBJECT manager; // manager to notify 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} TK TABLE METRICS, *P TK TABLE METRICS; O 

----- O 



msgTkTableSetMetrics 

Sets the metrics. 

Takes P_TK_TABLE_METRICS, returns STATUS. 

#define msgTkTableSetMetrics MakeMsg(clsTkTable, 6) 

Message typedef struct TK_TABLE_METRICS { 

Arguments TK_TABLE_STYLE style; // overall style 

OBJECT manager; // manager to notify 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} TK_TABLE_METRICS, *P_TK_TABLE_METRICS ; 

msgTkTableChildDefaults 

Sets the defaults in pArgs for a common child. 

Takes PJJNKNOWN, returns STATUS. 

tdefine msgTkTableChildDefaults MakeMsg(clsTkTable, 14) 

Comment pArgs should be an initialized (msgNewDefaults) P_NEW struct. 

Clients should use this on children manually inserted into the table. For example, send 
msgNewDefaults to class of child, then send msgTkTableChildDefaults to the table, then send 
msgNew to class of child, then add child to table with, e.g., msgTkTableAddAsLast. 

clsTkTable responds to msgTktTableChildDefaults as follows: 

♦ sets pArgs->win.device to self's device 

♦ turns on shared parent/child/sibling clipping: 

pArgs->win. flags. style |= wsParentClip; 

pArgs->win. flags. style &= ~ (wsClipSiblings | wsClipChildren) ; 

♦ if pArgs->object.class inherits from clsBorder, sets pArgs->border.style.backgroundInk to 
bsInkTransparent 

♦ if pArgs->object.class inherits from clsButton, sets pArgs->button.style.manager to 
bsManagerParent 

msgTkTableAddAsFirst 

Inserts pArgs as the first child in the table. 

Takes WIN, returns STATUS. 

#define msgTkTableAddAsFirst MakeMsg (clsTkTable, 9) 
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msgTkTableAddAsLast 

Inserts pArgs as the last child in the table. 

Takes WIN, returns STATUS. 

#define msgTkTableAddAsLast MakeMsg(clsTkTable, 10) 

msgTkTableAddAsSibling 

Inserts pArgs->newChild in front of or behind pArgs->sibling. 

Takes P_TK_TABLE_ADD_SIBLING, returns STATUS. 

#define msgTkTableAddAsSibling MakeMsg(clsTkTable, 11) 

uments typedef Struct TK_TABLE_ADD_SIBLING { 

WIN newChild; // new child to add 

WIN sibling; // existing child already in tkTable 

BOOLEAN before; // true: add before sibbling; false: after 

U32 spare; // unused (reserved) 

} TK_TABLE_ADD_SIBLING, *P_TK_TABLE_ADD_SIBLING; 

msgTkTableAddAt 

Inserts pArgs->newChild table at zero-based index pArgs->index. 

Takes P_TK_TABLE_ADD_AT, returns STATUS. 

#define msgTkTableAddAt MakeMsg(clsTkTable, 12) 

iimenfs typedef struct TK_TABLE_ADD_AT { 

WIN newChild; // new child to add 

U16 index; // zero-based desired index of newChild 

U32 spare; // unused (reserved) 

} TK TABLE ADD AT, *P TK TABLE ADD AT; 



msgTkTableRemove 

Extracts pArgs from the table. 

Takes WIN, returns STATUS. 

#define msgTkTableRemove MakeMsg(clsTkTable, 13) 



msgTkTablelnit 

Sent to TK_TABLE_ENTRY.class after default entry-to-pChildNew mappings. 
Takes P_TK_TABLE_INIT, returns STATUS. Category: third-party notification. 

#define msgTkTablelnit MsgNoError (MakeMsg(clsTkTable, 15)) 

typedef struct TK_TABLE_INIT { 

P_TK_TABLE_NEW pTkTableNew; // in: tkTable traversing the entry 

P_UNKNOWN pChildNew; // in: child new struct 

P_TK_TABLE_ENTRY pEntry; // in: this entry; out: last entry used 

U32 spare; // unused (reserved) 

} TK_TABLE_INIT, *P_TK_TABLE_INIT; 

The receiver should be sure to advance pArgs->pEntry to the last entry used. 
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TkTableFillArrayWithFonts 

Fills in an array of entries with the names of the currently installed fonts. 

Returns STATUS. 

Function Prototype STATUS EXPORTED TkTableFillArrayWithFonts ( 

OS_HEAP_ID heapld, // In: heap from which to allocate entries 

U16 prune, // In: controls pruning (see fontmgr.h) 

P_TK_TABLE_ENTRY * ppEntries // Out: pointer to array of entries 
); 

Comments This function allocates an array of TK_TABLE_ENTRY's from the heap given and then fills it in with the _ 

names of the fonts that are currently installed on the machine. The function sets each field of every entry O 
to null except for argl, which is set to point at a string allocated from the given heap. It is the client's 
responsibility to free this array and its strings when done using it. clsTkTable provides the utility 
function TkTableFreeArrayO for freeing this allocated storage. 

This function also sets the tag field of each entry to be the FIM_SHORT_ID of the corresponding font. 

TkTableFreeArray 

Frees an array of TK_TABLE_ENTRY's allocated by TkTableFillArrayWithFonts(). 

Returns STATUS. 

function Prototype STATUS EXPORTED TkTableFreeArray ( 

P_TK_TABLE_ENTRY pEntries // In: pointer to array of entries 
); 

Comments This function enumerates an array of TK_TABLE_ENTRY's, frees the string pointed to by the argl fields, 

and then frees the array itself. This function is meant to be used in concert with 
TkTableFillArrayWithFontsQ. 



Messages from Other Classes 



■rnments 



msgFree 

Sent as the last of three msgs to destroy an object. 

Takes OBJ_KEY, returns STATUS. 

Note that clsTkTable does not destroy metrics.manager. 



msgSave 

Causes an object to file itself in an object file. 

Takes P_OBJ_SAVE, returns STATUS. 

Note that clsTkTable will not save metrics.manager. 



msgControlGetClient 

Passes back the control's client. 

Takes P_UID, returns STATUS. 

clsTkTable responds as in msgTkTableGetClient. 
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msgControlSetClient 

Sets the control's client. 
Takes UID, returns STATUS. 
Comments clsTkTable responds as in msgTkTableSetClient. 



msgControlGetDirty 

Passes back true if the control has been altered since dirty was set false. 
Takes P_BOOLEAN, returns STATUS. 

Idefine msgControlGetDirty MakeMsg(clsControl, 15) 

Comments clsTkTable passes back true if any child is dirty. Each child is sent msgControlGetDirty. 



msgControlSetDirty 

Clears/sets the control's dirty bit. 
Takes BOOLEAN, returns STATUS. 
Comments clsTkTable sets the dirty bit on each child by sending msgControlSetDirty to each child. 



msgWinSend 

Sends a message up a window ancestry chain. 

Takes WIN_SEND, returns STATUS. 

clsTkTable will pass msgWinSend on to the tkTable's manager. 

If metrics.manager is objNull, does nothing and calls ancestor. 

Sends msgWinSend(pArgs) to metrics.manager. If the manager returns stsManagerContinue, calls 
ancestor; otherwise returns manager's return status. 
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TLAYOUT.H 



This file contains the API definition for clsTableLayout. 

clsTableLayout inherits from clsBorder. 

Table layout windows position (and optionally size) their child windows in a grid whose parameters you 
specify. 



Debugging Flags 

The clsTableLayout debugging flag is '%'. Defined values are: 
flag4 (0x0010) msgWinLayoutSelfinfo 
flag7 (0x0080) layout timing 



#ifndef TLAYOUT_INCLUDED 
tdefine TLAYOUT_INCLUDED 

tinclude <border.h> 

Common #defines and typedefs 
typedef OBJECT TBL LAYOUT; 






tifndef BORDER_INCLUDED 
#endif 



X and Y Alignment Styles 



tdefine tlAlignLeft 
#define tlAlignCenter' 
tdefine tlAlignRight 
tdefine tlAlignBottom 
tdefine tlAlignTop 
tdefine tlAlignBaseline 






// left- justified 


1 


// centered 


2 


// right- justified 


tlAlignLeft 


// bottom- justified 


tlAlignRight 


// top- justified 


3 


// vertical/horizontal baseline aligned 



Placement Styles 



tdefine tlPlaceRowMajor 
tdefine tlPlaceColMajor 
tdefine tlPlaceStack 
tdefine tlPlaceOrientation 



// across each row first 

1 // down each column first 

2 // stack on top of each other 

3 // landscape: RowMajor, portrait: ColMajor 



Extra Space Styles 



tdefine tlExtraNone 





tdefine tlExtraFirst 


1 


tdefine tlExtraAfterFirst 


2 


tdefine tlExtraLast 


3 


tdefine tlExtraBeforeLast 


4 


tdefine tlExtraAll 


5 


tdefine tlExtraBetweenAll 


6 


// 


7 


// 




// 


1 



// leave extra space alone 

// add extra space to 1st row/col 

// put extra space after 1st row/col 

// add extra space to last row/col 

// put extra space before last row/col 

// add extra space evenly to each row/col 

// divide extra space after each row/col 

// unused (reserved) 
// unused (reserved) 

// unused (reserved) 
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typedef struct TBL_LAYOUT_STYLE { 

U16 tblXAlignment : 2, 

tblYAlignment : 2, 

childXAlignment : 2, 

childYAlignment : 2, 

placement : 2 , 

growChildWidth : 1, 

growChildHeight : 1, 

senseOrientation: 1, 

reverseX : 1, 

reverseY : 1, 

wrap : 1 ; 

U16 widthExtra : 4, 

heightExtra : 4, 

spare 1 : 8; 

} TBL LAYOUT STYLE, *P TBL LAYOUT 



// table x alignment within window 

// table y alignment within window 

// 

// 

// 



child x alignment within grid cell 
child y alignment within grid cell 
order for placing children in the table 



// true to size child to col width 
// true to size child to row height 
// adjust according to current orientation 
// layout from right to left 
// layout from bottom to top 
// wrap around row/column 
// what to do with extra width 
// what to do with extra height 
// unused (reserved) 
STYLE; 



Default TBL LAYOUT STYLE: 



tblXAlignment 

tblYAlignment 

childXAlignment 

childYAlignment 

growChildWidth 

growChildHeight 

placement 

reverseX 

reverseY 

widthExtra 

heightExtra 



= tlLeft 

= tlTop 

= tlLeft 

= tlBottom 

= true 

= true 

= tlPlaceRowMajor 

= false 

= false 

= tlExtraNone 

= tlExtraNone 



constraints for Table Layout 

Enuml6(TBL_LAY0UT_C0NSTRAINT) { 

// for numRows, numCols, colWidth, rowHeight 

tlAbsolute =0, // fixed 

// for colWidth, rowHeight; can also or-in tlBaselineBox 



tlChildrenMax 

tlGroupMax 

// for numRows, 



tlMaxFit 


= 3, 


// 
// 
// 
// 


// for numRows, 


numCols 




tllnfinite 


= 4 


// 



= 1, // max of all children 

= 2, // max of all children on same row/column 

numCols, colWidth, rowHeight 

as many rows/cols as fit given current 
rowHeight, colWidth, gaps, and parent size 
or as wide a col/high a row as possible 
given current numRows, numCols 

// unbounded number of rows /cols 



}; 



The following can be OR'ed into tlChildrenMax or tlGroupMax to use max. ascender and descender of 
each child Note: not implemented for tlChildrenMax 

#define tlBaselineBox flag7 

The following can be OR'ed into any colWidth/rowHeight constraint to use the provided baseline 
rather than the max. baseline 

Note: not implemented yet. 

#define tlAbsoluteBaseline flag6 

The following can be OR'ed into any colWidth/rowHeight constraint to use tlMaxFit if the 
width/height is constrained during layout (i.e. wsLayoutResize is off or wsShrinkWrapWidth/Height is 
off). 

#define tlMaxFitlfConstrained flag8 

macros to extract the parts of a constraint 
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♦define TIConstraint (c) ((c) & OxF) 
typedef struct TBL_LAYOUT_COUNT { 

TBL_LAYOUT_CONSTRAINT constraint; // see above 

SI 6 value; // absolute value 

U32 spare; // unused (reserved) 

} TBL_LAYOUT_COUNT, *P_TBL_LAYOUT_COUNT; 

typedef struct TBL_LAYOUT_SIZE { 

TBL_LAYOUT_CONSTRAINT constraint; // see above 

SI 6 value; // absolute value 

S16 gap; // space between rows/columns 

S16 baseline; // absolute baseline (not implemented) 

U16 valueUnits : 6, // units for value/gap/baseline 

// (e.g. bsUnitsLayout) O 

sparel : 10; // unused (reserved) £ 

U32 spare; // unused (reserved) 5 

} TBL LAYOUT SIZE, *P TBL LAYOUT SIZE; 



typedef struct TBL_LAYOUT_METRICS { 

TBL_LAYOUT_COUNT numRows, numCols; 

TBL_LAYOUT_SIZE rowHeight, colWidth; 

TBL_LAYOUT_STYLE style; 

U32 spare; // unused (reserved) 

} TBL_LAYOUT_METRICS, *P_TBL_LAYOUT_METRICS; 

Pfr Status Values 

These are possible return values from msgWinLayoutSelf 

♦define stsTblLayoutLoop MakeStatus(clsTableLayout, 1) 

♦define stsTblLayoutBadConstraint MakeStatus(clsTableLayout, 2) 

msgNew 

Creates a table layout window. 

Takes P_TBL_LAYOUT_NEW, returns STATUS. Category: class message. 

typedef TBL_LAYOUT_METRICS TBL_LAYOUT_NEW_ONLY, *P_TBL_LAYOUT_NEW_ONLY; 
♦define tableLayoutNewFields \ 

borderNewFields \ 

TBL_LAYOUT_NEW_ONLY tableLayout ; 

Arguments typedef struct { 

tableLayoutNewFields 
} TBL_LAYOUT_NEW, *P_TBL_LAYOUT_NEW; 

Comments You first create a table layout window, then insert the children, then send msgWInLayout to layout the 

children. 

Note: if you are using tIAlignBaseline for the childX/YAlignment, you must use a colWidth/rowHeight 
constraint of tlGroupMax I tlBaselineBox. Baseline alignment is not implemented with other colWidth 
or rowHeight constraints. 

See Also msgWinLayoutSelf 



* 



msgNewDefaults 

Initializes the TBL_LAYOUT_NEW structure to default values. 

Takes P_TBL_LAYOUT_NEW, returns STATUS. Category: class message. 

Aessage typedef struct { 

irguments tableLayoutNewFields 

} TBL LAYOUT NEW, *P TBL LAYOUT NEW; 
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Comments Zeroes out pArgs->tableLayout and sets 



pArgs->win. flags. style |= 

wsShrinkWrapWidth | wsShrinkWrapHeight | wsFilelnline; 
pArgs->tableLayout. style. tblXAlignment = tlAlignLeft; 
pArgs->tableLayout.style.tblYAlignment = tlAlignTop; 
pArgs->tableLayout. style. childXAlignment = tlAlignLeft; 
pArgs->tableLayout. style. childYAlignment = tlAlignBottom; 
pArgs->tableLayout. style. growChildWidth = true; 
pArgs->tableLayout. style. growChildHeight = true; 

// Default is horizontal layout. 

pArgs->tableLayout.numRows. constraint = tlAbsolute; 
pArgs->tableLayout .numRows. value = 1; 

pArgs->tableLayout .numCols. constraint = tllnfinite; 
pArgs->tableLayout.numCols. value = 0; 

pArgs->tableLayout.rowHeight. constraint = tlChildrenMax; 
pArgs->tableLayout.rowHeight. value = 0; 
pArgs->tableLayout.rowHeight.gap = 0; 

pArgs->tableLayout.colWidth. constraint = tlGroupMax; 
pArgs->tableLayout.colWidth. value = 0; 
pArgs->tableLayout.colWidth.gap = 0; 



msgTblLayoutGetMetrics 

Passes back current metrics. 

Takes P_TBL_LAYOUT_METRICS, returns STATUS. 

tdefine msgTblLayoutGetMetrics MakeMsg(clsTableLayout, 1) 

Message typedef struct TBL_LAYOUT_METRICS { 

Arguments TBL_LAYOUT_COUNT numRows, numCols; 

TBL_LAYOUT_SIZE rowHeight, colWidth; 

TBL_LAYOUT_STYLE style; 

U32 spare; // unused (reserved) 

} TBL LAYOUT METRICS, *P TBL LAYOUT METRICS; 



msgTblLayoutSetMetrics 

Sets current metrics. 

Takes P_TBL_LAYOUT_METRICS, returns STATUS. 

#define msgTblLayoutSetMetrics MakeMsg(clsTableLayout, 2) 

Message typedef struct TBL_LAYOUT_METRICS { 

Arguments TBL_LAYOUT_COUNT numRows, numCols; 

TBL_LAYOUT_SIZE rowHeight, colWidth; 

TBL_LAYOUT_STYLE style; 

U32 spare; // unused (reserved) 

} TBL_LAYOUT_METRICS, *P_TBL_LAYOUT_METRICS; 

Comments clsTableLayout self-sends msgWinLayoutDirty(true). 

msgTblLayoutGetStyle 

Passes back current style values. 

Takes P_TBL_LAYOUT_STYLE, returns STATUS. 

tdefine msgTblLayoutGetStyle MakeMsg (clsTableLayout, 3) 
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typedef struct TBL_LAYOUT_STYLE { 
U16 tblXAlignment : 2, 
tblYAlignment : 2, 
childXAlignment : 2, 
childYAlignment : 2, 
placement : 2 , 
growChildWidth : 1, 
growChildHeight : 1, 
senseOrientation: 1, 
reverseX : 1, 
reverseY : 1, 
wrap : 1 ; 

U16 widthExtra : 4, 
heightExtra : 4, 
spare 1 : 8; 
} TBL LAYOUT STYLE, *P TBL LAYOUT 



// table x alignment within window 

// table y alignment within window 

// child x alignment within grid cell 

// child y alignment within grid cell 

// order for placing children in the table 

// true to size child to col width 

// true to size child to row height 

// adjust according to current orientation 

// layout from right to left 

// layout from bottom to top 

// wrap around row/column 

// what to do with extra width 

// what to do with extra height 

// unused (reserved) 
STYLE; 



msgTblLayoutSetStyle 

Sets style values. 

Takes P_TBL_LAYOUT_STYLE, returns STATUS. 

Idefine msgTblLayoutSetStyle MakeMsg (clsTableLayout, 4) 



typedef struct TBL_LAYOUT_STYLE { 

U16 tblXAlignment : 2, 

tblYAlignment : 2 , 

childXAlignment : 2, 

childYAlignment : 2, 

placement : 2, 

growChildWidth : 1, 

growChildHeight : 1, 

senseOrientation: 1, 

reverseX : 1, 

reverseY : 1, 

wrap : 1 ; 

U16 widthExtra : 4, 

heightExtra : 4, 

spare 1 : 8; 
} TBL LAYOUT STYLE, *P TBL LAYOUT 



// table x alignment within window 

// table y alignment within window 

// child x alignment within grid cell 

// child y alignment within grid cell 

// order for placing children in the table 

// true to size child to col width 

// true to size child to row height 

// adjust according to current orientation 

// layout from right to left 

// layout from bottom to top 

// wrap around row/column 

// what to do with extra width 

// what to do with extra height 

// unused (reserved) 
STYLE; 



clsTableLayout self-sends msgWinLayoutDirty(true). 



msgTblLayoutXYToIndex 



Determines a child zero-based index from an xy position. 

Takes P_TBL_LAYOUT_INDEX, returns STATUS. 

#define msgTblLayoutXYToIndex MakeMsg (clsTableLayout, 5) 

typedef struct TBL_LAYOUT_INDEX { 

XY32 xy; // In: table-relative coords 

U16 index; // Out: zero-based position at which to insert a child 

U32 spare; // unused (reserved) 

} TBL_LAYOUT_INDEX, *P_TBL_LAYOUT_INDEX; 

The index returned is such that if a child were inserted there and the table layed out, that child would be 
at the given xy. 
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msgTblLayoutAdjustSections 

Adjusts the border edges and margins of children to correctly reflect a sectioned table. 

Takes BOOLEAN, returns STATUS. 

#define msgTblLayoutAdjustSections MakeMsg (clsTableLayout, 6) 

Comments If you have a table layout window in one column and many rows, and the children have top or bottom 

border edges on to demarcate groups, you should send msgTblLayoutAdjustSections to the table layout 
window after you add or remove children. clsTableLayout will turn off borders that are not needed. 

If the table needs to be relayed out, msgWinLayout will be self-sent if pArgs is true; otherwise 
msgWinSetLayoutDirty(true) will be self-sent. 

Note that the current implementation assumes the table is one column, infinite rows. 

msgTblLayoutComputeGrid 

Computes the table grid parameters given the current constraints. 
Takes P_TBL_LAYOUT_GRID, returns STATUS. 

#define msgTblLayoutComputeGrid MakeMsg (clsTableLayout, 7) 
#define tblLayoutAvgChildren 10 

Arguments typedef Struct TBL_LAYOUT_GRID_VALUE { 

S32 value; // value in device units 
S32 maxBaseline; // max. baseline for the column/row 
S32 gap; // gap after row/col, in device units 

U32 spare; // unused (reserved) 
} TBL_LAYOUT_GRID_VALUE, *P_TBL_LAYOUT_GRID_VALUE; 

typedef struct TBL_LAYOUT_GRID { 

U16 numCols; // # of columns 

U16 numRows; // # of rows 

S32 colWidth; // column width if pColWidths is pNull 

S32 rowHeight; // row height if pRowHeights is pNull 

P_TBL_LAYOUT_GRID_VALUE pColWidths; // per-column widths, if not pNull 

P_TBL_LAYOUT_GRID_VALUE pRowHeights; // per-row heights, if not pNull 

TBL_LAYOUT_METRICS metrics; // actual metrics 

SIZE32 gap; // col/row gap, in device units 

U8 placement; // actual placement 

XY32 xy; // 1st grid cell in parent space 

// default storage for column widths, row heights 

TBL_LAYOUT_GRID_VALUE colWidthBuf [tblLayoutAvgChildren] ; 

TBL_LAYOUT_GRID_VALUE rowHeightBuf [tblLayoutAvgChildren] ; 

P_UNKN0WN pData; // reserved for clsTableLayout 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} TBL_LAYOUT_GRID, *P_TBL_LAYOUT_GRID; 

Comments This message is self-sent by clsTableLayout in response to msgWinLayoutSelf. clsTableLayout responds 

by computing all of the grid information based on the current TBL_IAYOUT_METRICS and current 
children. 

You can send this message at any time to determine the grid parameters. 

When you send msgTblLayoutComputeGrid, you must set pArgs->pData to pNull. 

You should send msgTblLayoutFreeGrid(pArgs) when finished to free any storage allocated by 
msgTblLayoutComputeGrid. 

If you subclass clsTableLayout, you can respond to this message and compute custom grid parameters 
(e.g. different per-column absolute column widths). 
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Note that pArgs->xy is not computed here. The location of the first grid cell can be computed by 
sending msgTblLayoutComputeGridXY. 

msgTblLayoutFreeGrid 

typical number of children in a table layout window 

msgTblLayoutComputeGridXY 

Computes the table grid start xy given the other grid parameters. 

Takes P_TBL_LAYOUT_GRID, returns STATUS. Q 

O 

#define msgTblLayoutComputeGridXY MakeMsg(clsTableLayout, 8) 

Message typedef Struct TBL_LAYOUT_GRID { 

Arguments U16 numCols; // # of columns 

U16 numRows; // # of rows 

S32 colWidth; // column width if pColWidths is pNull 

S32 rowHeight; // row height if pRowHeights is pNull 

P_TBL_LAYOUT_GRID_VALUE pColWidths; // per-column widths, if not pNull 
P_TBL_LAYOUT_GRID_VALUE pRowHeights;// per-row heights, if not pNull 
TBL_LAYOUT_METRICS metrics; // actual metrics 

SIZE32 gap; // col/row gap, in device units 

U8 placement; // actual placement 

XY32 xy; // 1st grid cell in parent space 

// default storage for column widths, row heights 
TBL_LAYOUT_GRID_VALUE colWidthBuf [tblLayoutAvgChildren] ; 
TBL_LAYOUT_GRID_VALUE rowHeightBuf [tblLayoutAvgChildren] ; 
P_UNKNOWN pData; // reserved for clsTableLayout 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} TBL_LAYOUT_GRID, *P_TBL_LAYOUT_GRID; 

Comments This message is self-sent by clsTableLayout in response to msgWinLayoutSelf. clsTableLayout responds 

by computing the lower-left of the first grid cell given the specified grid information. 

You should first send msgTblLayoutComputeGrid(pArgs) to compute the grid parameters, then send 
msgTblLayoutComputeGridXY to determine the location of the first cell. 

If style.reverseX is true, the first grid cell is actually at pArgs->xy.x - pArgs-> colWidth. 

If style.reverseY is true, the first grid cell is actually at pArgs->xy.y - pArgs->rowHeight. 

If you subclass clsTableLayout, you can respond to this message and compute a custom grid starting 
location (e.g. something not based on style. tblXAlignment or style.tblYAlignment). 

See Also msgTblLayoutComputeGrid 



msgTblLayoutFreeGrid 

Frees any storage allocated by msgTblLayoutComputeGrid. 

Takes P_TBL_LAYOUT_GRID, returns STATUS. 

#define msgTblLayoutFreeGrid MakeMsg (clsTableLayout, 9) 

Messoge typedef struct TBL_LAYOUT_GRID { 

Arguments U16 numCols; // # of columns 

U16 numRows; // # of rows 

S32 colWidth; // column width if pColWidths is pNull 

S32 rowHeight; // row height if pRowHeights is pNull 

P_TBL_LAYOUT_GRID_VALUE pColWidths; // per- column widths, if not pNull 

P_TBL_LAYOUT_GRID_VALUE pRowHeights;// per-row heights, if not pNull 

TBL LAYOUT METRICS metrics; // actual metrics 
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SIZE32 gap; // col/row gap, in device units 

U8 placement; // actual placement 

XY32 xy; // 1st grid cell in parent space 

// default storage for column widths, row heights 
TBL_LAYOUT_GRID_VALUE colWidthBuf [tblLayoutAvgChildren] ; 
TBL_LAYOUT_GRID_VALUE rowHeightBuf [tblLayoutAvgChildren ] ; 
PJJNKNOWN pData; // reserved for clsTableLayout 

U32 sparel; // unused (reserved) 

U32 spare2; // unused (reserved) 

} TBL_LAYOUT_GRID, *P_TBL_LAYOUT_GRID; 

imersts This message is self-sent by clsTableLayout after self-sending msgTblLayoutComputeGrid. 

You should send msgTblLayoutFreeGrid when finished with the grid information computed using 
msgTblLayoutComputeGrid to free any storage allocated by msgTblLayoutComputeGrid. 

Also msgTblLayoutComputeGrid 

Messages from other classes 

msgRestore 

Creates and restores an object from an object file. 

Takes P_OBJ_RESTORE, returns STATUS. 

meots clsTableLayout will self-send msgWinSetLayoutDirty(true) if the system font or system font scale 

changed since the table was filed. pArgs->pEnv is cast to a P_WIN_RESTOREJENV and must be a valid 
window environment pointer. 



msgWinLayoutSelf 

Tell a window to layout its children (sent during layout). 

Takes P_WIN_METRICS, returns STATUS. 

clsTableLayout responds by laying out its children. The grid cells of the table are computed based on the 
TBL_LAYOUT_METRICS specified. Each child is placed in the corresponding grid cell. 

clsTableLayout will self-send msgTblLayoutComputeGrid to compute the grid in which the children 
will be placed. msgTblLayoutComputeGridXY will be self-sent to determine the origin of the grid in 
selfs window. 

The number of columns and rows are computed based on the numCols and numRows constraints. The 
width and height of each column and row are computed based on the colWidth and rowHeight 
constraints. 

The children are placed acording to style.placement. For example, if style.placement is 
tlPlaceRowMajor, the children are placed across the first row, then the next row, etc.. If style.placement 
is tlPlaceOrientation, then the placement will be based on the current orientation of selfs window 
device: 

Orientation Placement 

orientPortraitNormal tlPlaceColMajor 
orientPortraitReverse tlPlaceColMajor 
orientLandscapeNormal tlPlaceRowMajor 
orientLandscapeReverse tlPlaceRowMajor 



msgControlEnable 

The control re-evaluates whether it is enabled. 

Takes P_CONTROL_ENABLE, returns STATUS. 

Comments clsTableLayout recursively enumerates its children (i.e. wsEnumRecursive option to msgWinEnum) 

and forwards this message to each child that inherits from clsControl. This allows each control in the 
table to respond to alter its enabled state. 

This is used by, for example, clsMenuButton when menuButton.style.enableMenu is set to true. 

See Also clsMenuButton 
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Messages from other classes 

If style.senseOrientation is true and the orientation is Landscape, the layout metrics are "swapped" as 
follows: 

if style.placement is tlPlaceRowMajor, tlPlaceColMajor is usedif style.placement is tlPlaceColMajor, 
tlPlaceRowMajor is used 

metrics. numRows and metrics.numCols are swapped. rowHeight and metrics.colWidth are swapped 

So if you want a layout that is sensitive to the orientation, set the constraints to make sense for Portrait 
orientation and turn on style.senseOrientation. If the orientation is Landscape when the window is 
layed out, the metrics will be altered for you. 

Within each grid cell, each child is aligned acording to style. childXAlignment and style.yAlignment. O 

For example, if style. childXAlignment and style.childYAlignment are both tlAlignCenter, the children 
are centered in each grid cell. 

If style.growChildWidth/Height is true, the width/height of each child is set to the width/height of the 
child's grid cell. 

The entire table is aligned within self acording to style.tblXAlignment and style.tblYAlignment. For 
example, if style.tblXAlignment and style.tblYAlignment are both tlAlignCenter, the table is centered 
in selfs window. 

The rows and columns of the table are normally filled out top to bottom, left to right. If style.reverseY is 
true, the rows are filled out bottom to top. If style.reverseX is true, the columns are filled out right to 
left. 

If pArgs->options has wsLayoutResize on and self has shrink wrap width/height on, the width and 
height of the resulting table will be passed back in pArgs->bounds.size. 

Return Value stsTblLayoutLoop The specified set of constraints results in a circular layout loop. For example, 

tlMaxFit for numCols and tlMaxFit for colWidth. 

stsTblLayoutBadConstraint A constraint specified is not a valid value. 

msgWinGetBaseline 

Gets the desired x,y alignment of a window. 

Takes P_WIN_METRICS, returns STATUS. 

Comments If the table is one column, clsTableLayout will return the x-baseline of the first child in the table (i.e. 

send msgWinGetBaseline to the first child). Otherwise the x-baseline will be zero. 

If the table is one row, clsTableLayout will return the y-baseline of the first child in the table (i.e. send 
msgWinGetBaseline to the first child). Otherwise the y-baseline will be zero. 
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TRACK.H 



This file contains the API definition for clsTrack. 

clsTrack inherits from clsObject. 

Provides transient drawing feedback for various pen dragging situations, such as resizing and dragging 
frames. 



Debugging Flags 



The clsTrack debugging flag is 'K'. Defined values are: 
flagl 5 (0x8000) general debug info 

#ifndef TRACK_INCLUDED 
#define TRACK_INCLUDED 

♦include <win.h> 

Common #defines and typedefs *********** 



#ifndef WIN_INCLUDED 
#endif 



Track Styles 



#define tsTrackMove 
♦define tsTrackResize 1 



Anchor Styles 



#define 


tsAnchorUL 





// 


upper- left 


♦define 


tsAnchorUR 


1 


// 


upper-right 


♦define 


tsAnchorLR 


2 


// 


lower-right 


#define 


tsAnchorLL 


3 


// 


lower-left 



Draw Styles 



♦define 
♦define 
♦define 
#define 
#define 
♦define 
♦define 



tsDrawRect 

tsDrawTabBarRect 1 

tsDrawCmdBarRect 2 

tsDrawTabCmdBarRect 3 

tsDrawBitmap 4 

tsDrawViaMessages 5 

tsDrawDoubleRect 6 



// simple rectangle 

// rectangle with vertical tab bar on right 

// rectangle with command bar at bottom 

// rectangle with both tab and command bars 

// not implemented 

// forward msgTrackShow/Hide to client 

// double rect as in clsBorder double thickness 



Thickness Styles 



♦define tsThicknessSingle 
♦define tsThicknessDouble 1 



// single-thick lines 
// double-thick lines 



612 PENPOINT API REFERENCE 

Part 4 / Ul Toolkit 



Line Pattern Styles 



tdefine tsP at Foreground 
♦define tsPatDashed 1 
// 2 

// 3 

typedef struct TRACKJSTYLE { 
U16 track 

anchor 

draw 

update 

autoDestroy 

thickness 

pattern 

start Thickness 
U16 useThreshold 

spare 
} TRACK STYLE, *P TRACK STYLE; 



// foreground ink 
// sysDcPatLD50 
// unused (reserved) 
// unused (reserved) 

2, // track style (move or resize) 

2, // corner to anchor (tsTrackResize only) 

4, // visual to draw 

1, // send msgTrackUpdate to client 

1, // destroy self when done 

2, // thickness of drawn lines 

2, // line pattern of drawn lines 

2; // thickness of initial drawn lines 

1, // start tracking after msgPenMoveDown 

15; // reserved 
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msgNew 

Creates a tracker. 

Takes P_TRACK_NEW, returns STATUS. Category: class message. 



typedef struct TRACK_NEW_ONLY { 



TRACK_STYLE 


style; 




WIN 


win; 


// 


OBJECT 


client; 


// 


PJJNKNOWN 


image ; 


// 


PJJNKNOWN 


clientData; 


// 


OBJECT 


tracker; 


// 


RECT32 


initRect; 


// 


RECT32 


rect ; 


// 


S32 


tabBarW; 


// 


S32 


cmdBarH; 


// 


XY32 


origXY; 


// 


XY32 


curXY; 


// 


TAG 


tag; 


// 


// if tsTrackMove 




RECT32 


keepRect ; 


// 


RECT32 


constrainRect ; 


// 


// if tsTrackResize 




SIZE32 


minWH; 


// 


SIZE32 


maxWH; 


// 


U32 


spare; 


// 


U32 


spare 1; 


// 



objNull means use theRootWindow 

client to send msgTrackDone to 

optional image instead of box (not implemented) 

data for client to set 

ignored in msglnit 

in device units, relative to win 
relative to win 
I tsDrawTabCmdBarRect 
I tsDrawTabCmdBarRect 
relative to win 
relative to win 



in device units, 
tsDrawTabBarRect 
tsDrawCmdBarRect 
in device units, 
in device units, 



optional distinguishing tag 

in device units, relative to win 
in device units, relative to win 

in device units 
in device units 
unused (reserved) 
unused (reserved) 
} TRACK_METRICS, *P_TRACK_METRICS, 
TRACK_NEW_ONLY, *P_TRACK_NEW_ONLY; 

tdefine trackNewFields \ 
objectNewFields \ 
TRACK_NEW_ONLY t rack ; 

typedef struct TRACK_NEW { 

trackNewFields 
} TRACK_NEW, *P_TRACK_NEW; 

Note that if you change the default value for pArgs->track.constrainRect you should also insure 
pArgs->track.keepRect is correct for your new constrainRect. 

Here is some sample code for creating an instance of clsTrack to resize a window. This is taken from 
clsGrabBox. plnst->client is the window to be resized. 

// distance to stay away from edge of parent after resize, in device units 
tdefine trBottomParentMargin 
tdefine trRightParentMargin 
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// min. distance from bottom of child to top of parent, in device units 
♦define trTopParentMargin 12 

// min. distance from right of child to left of parent, in device units 
♦define trLeftParentMargin 12 

// absolute minimum resize width and height, in device units 
♦define trMinResizeWidth 20 
♦define trMinResizeHeight 20 

TRACK_NEW tn; 

// start a resize tracker — 

ObjCallRet (msgNewDefaults, clsTrack, &tn, s) ; O 



ObjCallRet (msgWinGetMetrics, plnst->client, &wm, s) ; 

tn. track. style. track = tsTrackResize; 

tn. track. win = wm. parent; 

tn. track. client = self; 

tn. track. clientData = plnst->client; // window being resized 

tn. track. tag = tagBorderResize; 

tn.track.initRect = wm. bounds; 

// don't allow the grabbox to go off the edge of client's parent 
ObjCallRet (msgWinGetMetrics, wm. parent, &rm, s) ; 

tn.track.maxWH.w = rm. bounds. size. w - trRightParentMargin - 

wm . bounds . origin . x; 
tn.track.maxWH.h = RectTop(&wm. bounds) - trBottomParentMargin; 

tn.track.minWH.w = RectRight (&wm. bounds) - (rm. bounds. si ze.w - trLeftParentMargin); 
tn.track.minWH.h = Rect Top (&wm. bounds) - (rm. bounds. size. h - trTopParentMargin); 

tn.track.minWH.w = Max (tn.track.minWH.w, trMinResizeWidth); 
tn.track.minWH.h = Max (tn.track.minWH.h, trMinResizeHeight); 

switch (pInst->style.loc) { 
case gbLocTopEdge : 
case gbLocULCorner : 

tn. track. style. anchor = tsAnchorLR; 

break; 

case gbLocRightEdge : 
case gbLocURCorner : 

tn. track. style. anchor = tsAnchorLL; 

break; 

case gbLocLeftEdge : 
case gbLocLLCorner : 

tn. track. style. anchor = tsAnchorUR; 

break; 

case gbLocBottomEdge : 
default : 

tn. track. style. anchor = tsAnchorUL; 

break; 
} 

switch (pInst->style.loc) { 
default : 

// unconstrained 
break; 
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case gbLocLef tEdge : 

case gbLocRightEdge : 

// constrained to horizontal 
tn.track.minWH.h = wm. bounds. size. h; 
tn.track.maxWH.h = wm. bounds. size. In- 
break; 

case gbLocBottomEdge : 
case gbLocTopEdge : 

// constrained to vertical 

tn. track. minWH.w = wm. bounds. size. w; 

tn.track.maxWH.w = wm. bounds. size. w; 

break; 
} 

ObjCallRet (msgTrackProvideMetrics, plnst->client, &tn. track, s) ; 
Ob jCallRet (msgNew, clsTrack, &tn, s) ; 

// start tracking at the initial down point 

wm. bounds. origin = *pXY; 

ObjCallRet (msgWinTransformBounds, theRootWindow, &wm, s) ; 

ObjCallRet (msgTrackStart , tn.object.uid, &wm. bounds. origin, s) ; 

Here is some sample code for creating an instance of clsTrack to drag a window. This is taken from 
clsBorder. deltaWIn is the window to be dragged. 

// keep rect size for drag, in device units 
tdefine trDefaultMoveKeep 12 

TRACK_NEW tn; 

ObjCallRet (msgNewDefaults, clsTrack, &tn, s) ; 

// constraint to parent's bounds 

ObjSendUpdateRet (msgWinGetMetrics, deltaWin, &clientMetrics, SizeOf (clientMetrics) , s); 
if ( ! clientMetrics . parent ) 
return stsOK; 

ObjSendUpdateRet (msgWinGetMetrics, clientMetrics. parent, &wm, SizeOf (wm), s); 

tn. track. style. startThickness = tsThicknessDouble; 

tn. track. win = clientMet rics. parent; 

tn. track. client = self; 

tn. track. clientData = deltaWin; 

tn.track.initRect = clientMet rics. bounds ; 

tn. track. constrainRect. size = wm. bounds. size ; 

tn. track. tag = tagBorderDrag; 

// start tracking at the initial point 

wm. parent = clientMet rics. parent ; 

wm. bounds. origin = *pXY; 

ObjCallRet (msgWinTransformBounds, self, &wm, s) ; 

tn. track. keepRect. size. w = tn. track. keepRect. size. h = trDefaultMoveKeep; 

tn. track. keepRect. origin = wm. bounds. origin ; 

tn. track. keepRect. origin. x -= trDefaultMoveKeep / 2; 

tn. track. keepRect. origin. y -= trDefaultMoveKeep / 2; 

ObjSendUpdateRet (msgTrackProvideMetrics, deltaWin, &tn. track, SizeOf (tn. track) , s); 
Ob jCallRet (msgNew, clsTrack, &tn, s); 

ObjCallRet (msgTrackStart, tn.object.uid, &wm. bounds. origin, s) ; 
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irgymenfs 



msgNewDefaults 

Initializes the TRACKJNEW structure to default values. 

Takes P_TRACK_NEW, returns STATUS. Category: class message. 

typedef struct TRACK_NEW { 

trackNewFields 
} TRACK_NEW, *P_TRACK_NEW; 

Sets all of pArgs->track to 0, then ... 



pArgs->ob ject . cap |= objCapCall; 
pArgs->track . style . autoDestroy 
pArgs ->t rack . const rainRect . s i ze . w 
pArgs->track . constrainRect . size . h 
pArgs->track . keepRect . origin . x 
pArgs->track . keepRect . origin . y 
pArgs->track . keepRect . size . w 
pArgs->track . keepRect . size . h 
pArgs->t rack . maxWH . w 
pArgs->track . maxWH . h 



true; 
maxS32 / 
maxS32 / 
maxS32 / 
maxS32 / 
1; 
1; 

maxS32 / 
maxS32 / 



Default style: 



track 

anchor 

draw 

update 

autoDestroy 

thickness 

pattern 

start Thickness 

useThreshold 



= tsTrackMove 

= tsAnchorUL 

= tsDrawRect 

= false 

= true 

= tsThicknessSingle 

= tsPatForeground 

= tsThicknessSingle 

= false 



(ignored when tsTrackMove) 



tessoge 
yrgumerr 



msgTrackGetStyle 

Passes back current style values. 

Takes P_TRACK_STYLE, returns STATUS. 

#define msgTrackGetStyle MakeMsg(clsTrack, 1) 



typedef struct TRACK_STYLE { 



U16 


track 


2, 




anchor 


2, 




draw 


4, 




update 


1, 




autoDestroy 


1, 




thickness 


2, 




pattern 


2, 




start Thickness 


2; 


U16 


useThreshold 


1, 




spare 


15; 


} TRACK 


STYLE, *P_TRACK_STYLI 


2; 



// track style (move or resize) 

// corner to anchor (tsTrackResize only) 

// visual to draw 

// send msgTrackUpdate to client 

// destroy self when done 

// thickness of drawn lines 

// line pattern of drawn lines 

// thickness of initial drawn lines 

// start tracking after msgPenMoveDown 

// reserved 



msgTrackSetStyle 



Sets style values. 

Takes P_TRACK_STYLE, returns STATUS. 

tdefine msgTrackSetStyle MakeMsg(clsTrack, 2) 
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typedef struct TRACK STYLE 



Comments 



track style (move or resize) 

corner to anchor (tsTrackResize only) 

visual to draw 

send msgTrackUpdate to client 

destroy self when done 

thickness of drawn lines 

line pattern of drawn lines 

thickness of initial drawn lines 

start tracking after msgPenMoveDown 

reserved 



If the new style values result in a different visual, and msgTrackStart has been sent, you should first send 
msgTrackHide with pArgs of the old TRACK_METRICS, then msgTrackSetStyle, then msgTrackShow 
with the new TRACK METRICS. 



U16 


track 


2, 


// 




anchor 


2, 


// 




draw 


4, 


// 




update 


1, 


// 




autoDestroy 


1, 


// 




thickness 


2, 


II 




pattern 


2, 


II 




start Thickness 


2; 


II 


U16 


useThreshold 


1, 


II 




spare 


15; 


II 


} TRACK_ 


STYLE, *P_TRACK STYLE; 





msgTrackGetMetrics 

Passes back the current metrics. 

Takes P_TRACK_METRICS, returns STATUS. 

#define msgTrackGetMetrics MakeMsg(clsTrack, 3) 



typedef struct TRACK NEW ONLY { 



TRACK_STYLE 


style; 




WIN 


win; 


// 


OBJECT 


client; 


// 


P UNKNOWN 


image ; 


// 


PJJNKNOWN 


clientData; 


// 


OBJECT 


tracker; 


// 


RECT32 


initRect ; 


// 


RECT32 


rect ; 


// 


S32 


tabBarW; 


// 


S32 


cmdBarH; 


// 


XY32 


origXY; 


// 


XY32 


curXY; 


// 


TAG 


tag; 


// 



// objNull means use theRootWindow 

client to send msgTrackDone to 

optional image instead of box (not implemented) 
// data for client to set 

ignored in msglnit 

in device units, relative to win 



in device units, 
tsDrawTabBarRect 
// tsDrawCmdBarRect 
in device units, 
in device units, 



relative to win 
I tsDrawTabCmdBarRect 
| tsDrawTabCmdBarRect 
relative to win 
relative to win 



// if tsTrackMove 
RECT 3 2 keepRect; 
RECT32 constrainRect; 
// if tsTrackResize 



optional distinguishing tag 



// in device units, relative to win 
//in device units, relative to win 



SIZE32 


minWH; 


// 


in device units 


SIZE32 


maxWH; 


// 


in device units 


U32 


spare; 


// 


unused (reserved) 


U32 


spare 1; 


// 


unused (reserved) 


TRACK METRICS, 


*P TRACK METRICS, 







msgTrackSetMetrics 



Sets the metrics. 

Takes P_TRACK_METRICS, returns STATUS. 

tdefine msgTrackSetMetrics MakeMsg(clsTrack, 4) 



typedef struct TRACK NEW ONLY { 



TRACK_STYLE 


style; 


WIN 


win; 


OBJECT 


client; 


PJJNKNOWN 


image; 


PJJNKNOWN 


clientData; 


OBJECT 


tracker; 


RECT32 


initRect; 



// objNull means use theRootWindow 

// client to send msgTrackDone to 

// optional image instead of box (not implemented) 

// data for client to set 

// ignored in msglnit 

// in device units, relative to win 
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RECT32 


rect ; 


// 


S32 


tabBarW; 


// 


S32 


cmdBarH; 


// 


XY32 


origXY; 


// 


XY32 


curXY; 


// 


TAG 


tag; 


// 



in device units, 
tsDrawTabBarRect 
tsDrawCmdBarRect 
in device units, 
in device units, 



relative to win 
I tsDrawTabCmdBarRect 
I tsDrawTabCmdBarRect 
relative to win 
relative to win 



// if tsTrackMove 
RECT32 keepRect; 
RECT32 const rainRect; 
// if tsTrackResize 



optional distinguishing tag 



//in device units, relative to win 
//in device units, relative to win 



SIZE32 


minWH; 


// 


in device units 


SIZE32 


maxWH; 


// 


in device units 


U32 


spare; 


// 


unused (reserved) 


U32 


sparel; 


// 


unused (reserved) 


} TRACK_METRICS, 


*P_TRACK_METRICS , 







Comments See msgTrackSetStyle for notes on changing metrics after msgTrackStart has been sent. 
See Also msgTrackSetStyle 



msgTrackStart 

Starts the tracker. 

Takes P_XY32, returns STATUS. 

tdefine msgTrackStart MakeMsg(clsTrack, 5) 

The pArgs indicates the initial position of the pen (in device units, in the space of the metrics. win). If 
pArgs is pNull, then metrics.origXY is used as the initial pen position. 

clsTrack will do the following: 

♦ self-send msgTrackConstrain to constrain the initial point. 

♦ grab all input events using InputSetGrab(). 

♦ self-send msgTrackShow(&metrics) to paint the tracker. 



Client Messages 



msgTrackDone 

Sent by clsTrack to metrics.client when the track is done. 

Takes P_TRACK_METRICS, returns STATUS. Category: client notification. 

tdefine msgTrackDone MakeMsg (clsTrack, 6) 



typedef struct TRACK_NEW_ONLY { 

TRACK_STYLE Style; 

WIN win; 

OBJECT client; 

PJJNKNOWN image; 

PJJNKNOWN clientData; 

OBJECT tracker; 

RECT32 initRect; 

RECT 3 2 rect; 

S32 tabBarW; 

S32 cmdBarH; 

XY32 origXY; 

XY32 curXY; 

TAG tag; 
// if tsTrackMove 

RECT32 keepRect; 



// objNull means use theRootWindow 
// client to send msgTrackDone to 
// optional image instead of box (not implemented) 
// data for client to set 
ignored in msglnit 
in device units, relative to win 
relative to win 
I tsDrawTabCmdBarRect 
I tsDrawTabCmdBarRect 
relative to win 
//in device units, relative to win 
// optional distinguishing tag 

//in device units, relative to win 



// 

// 

//in device units, 

// tsDrawTabBarRect 

// tsDrawCmdBarRect 

// in device units, 
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Argument 



RECT32 



constrainRect; // in device units, relative to win 



// if tsTrackResize 



SIZE32 




minWH; 


// 


in device units 


SIZE32 




maxWH; 


// 


in device units 


U32 




spare; 


// 


unused (reserved) 


U32 




spare 1; 


// 


unused (reserved) 


} TRACK_METRICS, 


* p . 


_TRACK METRICS, 







msgTrackUpdate 

Sent by clsTrack to metrics.client when the pen moves if style. update is true. 
Takes P_TRACK_METRICS, returns STATUS. Category: client notification, 
tdefine msgTrackUpdate MakeMsg (clsTrack, 7) 



typedef struct TRACK NEW ONLY { 



TRACK_STYLE 


style; 




WIN 


win; 


// 


OBJECT 


client; 


// 


P_UNKNOWN 


image ; 


// 


PJJNKNOWN 


clientData; 


// 


OBJECT 


tracker; 


// 


RECT32 


initRect; 


// 


RECT32 


rect ; 


// 


S32 


tabBarW; 


// 


S32 


cmdBarH; 


// 


XY32 


origXY; 


// 


XY32 


curXY; 


// 


TAG 


tag; 


// 



// objNull means use theRootWindow 

client to send msgTrackDone to 

optional image instead of box (not implemented) 

data for client to set 

ignored in msglnit 

in device units, relative to win 
relative to win 
I tsDrawTabCmdBarRect 
I tsDrawTabCmdBarRect 
relative to win 
relative to win 



in device units, 
tsDrawTabBarRect 
t s D r awCmdBa rRe c t 
in device units, 
in device units, 



// if tsTrackMove 
RECT32 keepRect; 
RECT32 constrainRect; 
// if tsTrackResize 



// optional distinguishing tag 

// in device units, relative to win 
// in device units, relative to win 



SIZE32 


minWH; 


// 


in device units 


SIZE32 


maxWH; 


// 


in device units 


U32 


spare; 


// 


unused (reserved) 


U32 


spare 1; 


// 


unused (reserved) 


TRACK METRICS, 


*P TRACK METRICS, 







msgTrackProvideMetrics 

Sent to a tracker client before tracker is created. 

Takes P_TRACK_METRICS, returns STATUS. Category: third-party notification. 

#define msgTrackProvideMetrics MsgNoError (MakeMsg (clsTrack, 9)) 



typedef struct TRACK NEW ONLY { 



TRACK_STYLE 


style; 




WIN 


win; 


// 


OBJECT 


client; 


// 


P_UNKNOWN 


image; 


// 


P UNKNOWN 


clientData; 


// 


OBJECT 


tracker; 


// 


RECT32 


initRect; 


// 


RECT32 


rect; 


// 


S32 


tabBarW; 


// 


S32 


cmdBarH; 


// 


XY32 


origXY; 


// 


XY32 


curXY; 


// 


TAG 


tag; 


// 



objNull means use theRootWindow 

client to send msgTrackDone to 

optional image instead of box (not implemented) 
// data for client to set 

ignored in msglnit 

in device units, relative to win 
relative to win 
I tsDrawTabCmdBarRect 
I tsDrawTabCmdBarRect 
relative to win 
relative to win 



in device units, 
tsDrawTabBarRect 
tsDrawCmdBarRect 
in device units, 
in device units, 



// if tsTrackMove 

RECT 3 2 keepRect; 

RECT32 constrainRect; 



optional distinguishing tag 



// in device units, relative to win 
// in device units, relative to win 



Comment's 
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// if t 


sTrackResize 






SIZE32 


minWH; 


//in device units 




SIZE32 


maxWH; 


//in device units 




U32 


spare ; 


// unused (reserved) 




U32 


spa re 1; 


// unused (reserved) 
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} TRACK METRICS, *P TRACK METRICS, 



Before it sends msgNew to clsTrack, code creating a tracker may choose to send out this message to 
another object, allowing it to modify the tracker metrics. See frame.h for a sample response to 
msgTrackProvideMetrics . 



Self-sent Messages 



msgTrackConstrain 

Constrains a point. 

Takes P_XY32, returns STATUS. Category: self-sent, 
tdefine msgTrackConstrain MakeMsg (clsTrack, 8) 

If style.track is tsTrackMove, a new value for metrics.keepRect is computed based on the offset from 
metrics. origXY to pArgs. pArgs is altered to insure the new keepRect lies within metrics. constrainRect. 

If style.track is tsTrackResize, a new value for metrics.rect is computed based on the offset from 
metrics.origXY to pArgs. pArgs is altered to insure the new rect.size lies within metrics. maxWH and 
metrics . minWH . 



msgTrackShow 

Displays the tracker visuals at pArgs->rect. 

Takes P_TRACK_METRICS, returns STATUS. Category: self-sent. 

tdefine msgTrackShow MakeMsg (clsTrack, 10) 



typedef struct TRACK_NEW_ONLY { 



TRACK_STYLE 


style; 




WIN 


win; 


// 


OBJECT 


client; 


// 


P_UNKN0WN 


image ; 


// 


PJJNKNOWN 


clientData; 


// 


OBJECT 


tracker; 


// 


RECT32 


initRect ; 


// 


RECT32 


rect ; 


// 


S32 


tabBarW; 


// 


S32 


cmdBarH; 


// 


XY32 


origXY; 


// 


XY32 


curXY; 


// 


TAG 


tag; 


// 



//if tsTrackMove 
RECT32 keepRect; 
RECT32 constrainRect; 
// if tsTrackResize 



SIZE32 




minWH; 


SIZE32 




maxWH; 


U32 




spare; 


U32 




sparel ; 


TRACK_METRICS, 


* P 


_TRACK_METRICS, 



objNull means use theRootWindow 

client to send msgTrackDone to 

optional image instead of box (not implemented) 
// data for client to set 

ignored in msglnit 

in device units, relative to win 
relative to win 
| tsDrawTabCmdBarRect 
I tsDrawTabCmdBarRect 
relative to win 
relative to win 



in device units, 
tsDrawTabBarRect 
tsDrawCmdBarRect 
in device units, 
in device units, 



// optional distinguishing tag 

//in device units, relative to win 
// in device units, relative to win 

//in device units 
//in device units 
// unused (reserved) 
// unused (reserved) 



clsTrack will self-send this message when the tracker needs to be displayed. 
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msgTrackHide 

Removes the tracker visuals at pArgs->rect. 

Takes P_TRACK_METRICS, returns STATUS. Category: self-sent. 

Idefine msgTrackHide MakeMsg(clsTrack, 11) 



typedef struct TRACK NEW ONLY { 



TRACK_STYLE 

WIN 

OBJECT 

P_UNKNOWN 

PJJNKNOWN 

OBJECT 

RECT32 

RECT32 

S32 

S32 

XY32 

XY32 

TAG 



style; 

win; 

client; 

image; 

clientData; 

tracker; 

initRect; 

rect; 

tabBarW; 

cmdBarH; 

origXY; 

curXY; 

tag; 



// objNull means use theRootWindow 

// client to send msgTrackDone to 

// optional image instead of box (not implemented) 

// data for client to set 

// ignored in msglnit 

// in device units, relative to win 

// in device units, relative to win 

I tsDrawTabCmdBarRect 

I tsDrawTabCmdBarRect 

relative to win 

relative to win 



in device units, 
// tsDrawTabBarRect 
// tsDrawCmdBarRect 
in device units, 
in device units, 



// 
// 
// 



optional distinguishing tag 



// if tsTrackMove 
RECT32 keepRect; 
RECT32 constrainRect; 
// if tsTrackResize 



// in device units, relative to win 
// in device units, relative to win 

// in device units 
// in device units 
// unused (reserved) 
// unused (reserved) 



clsTrack will self-send this message when the tracker needs to be erased. 



SIZE32 




minWH; 


SIZE32 




maxWH; 


U32 




spare ; 


U32 




spare 1; 


TRACK METRICS, 


*p 


TRACK METRICS, 



Messages from other classes 



msglnputEvent 

Notification of an input event. 

Takes P_INPUT_EVENT, returns STATUS. 

clsTrack will respond to input events by updating and/or terminating the tracker. 

If pArgs->devCode is not one of msgPenMoveDown, msgPenUp, or msgPenOutProxDown 
stsInputGrabTerminate is returned. 

The new point is constrained by self-sending msgTrackConstrain. The new value for metrics.rect and 
metrics.curXY is computed based on the constrained pArgs->xy. 

If pArgs->devCode is msgPenUp or msgPenOutProxDown, clsTrack does the following: 

♦ send msgTrackDone (&metrics) to metrics.client 

♦ self-send msgTrackHide to remove the old tracker visuals 

♦ if style.autoDestroy is true, self-send msgDestroy(pNull) 

If pArgs->devCode is msgPenMoveDown, and the constrained version of pArgs->xy is different from 
metrics.curXY, clsTrack does the following: 

♦ if style. update is true, send msgTrackUpdate(&metrics) to metrics.client 

♦ self-send msgTrackHide to remove the old tracker visuals 

♦ self-send msgTrackShow to paint the new tracker visuals 



m$mtm 
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TTABLE.H 



This file contains the API definition for clsToggleTable. 
clsToggleTable inherits from clsTkTable. 

Toggle tables implement non-exclusive choices. 



#ifndef TTABLE_INCLUDED 
#define TTABLE_INCLUDED 

linclude <tktable.h> 



tifndef TKTABLE_INCLUDED 
#endif 



Common #defines and typedefs 



imenfs 



typedef OBJECT TOGGLE_TABLE ; 

msgNew 

Creates a toggle table window. 

Takes P_TOGGLE_TABLE_NEW, returns STATUS. Category: class message. 

typedef struct TOGGLE_TABLE_NEW_ONLY { 

U32 spare; // unused (reserved) 

} TOGGLE_TABLE_NEW_ONLY, *P_TOGGLE_TABLE_NEW_ONLY; 

#define toggleTableNewFields \ 
tkTableNewFields \ 

TOGGLE_TABLE_NEW_ONLY toggleTable ; 

typedef struct TOGGLE_TABLE_NEW { 

toggleTableNewFields 
} TOGGLE TABLE NEW, *P TOGGLE TABLE NEW; 



msgNewDefaults 

Initializes the TOGGLE_TABLE_NEW structure to default values. 

Takes P_TOGGLE_TABLE_NEW, returns STATUS. Category: class message. 

typedef struct TOGGLE_TABLE_NEW { 

toggleTableNewFields 
} TOGGLE_TABLE_NEW, *P_TOGGLE_TABLE_NEW; 

Sets the following values: 

pArgs->gWin. style. gestureEnable = false; 

pArgs->tableLayout. style. growChildHeight = false; 
pArgs->tableLayout. style. growChildWidth = true; 

pArgs->tableLayout.numCols. constraint = tlAbsolute; 
pArgs->tableLayout.numCols. value = 1; 

pArgs->tableLayout.numRows. constraint = tllnfinite; 
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pArgs->tableLayout.colWidth. constraint = tlChildrenMax; 
pArgs->tableLayout.colWidth.gap = 0; 

pArgs->tableLayout .rowHeight . constraint = tlGroupMax; 
pArgs->tableLayout.rowHeight.gap = 0; 

Messages from Other Classes 

msgTkTableChildDefaults 

Sets the defaults in P_ARGS for a common child. 

Takes PJJNKNOWN, returns STATUS. 

Comments Here is how a choice processes this message: 

if <pArgs->object .class inherits from clsGWin> 
pArgs->gWin. style. gestureEnable = false; 

if <pArgs->object .class inherits from clsBorder> { 

pArgs->border. style. edge = bsEdgeNone; 

pArgs->border. style. topMargin = 1; 

pArgs->border. style. bottomMargin = 1; 
} 

if <pArgs->object .class inherits from clsLabel> 
pArgs->label . style . xAlignment = IsAlignLef t ; 

if <pArgs->object. class inherits from clsButton> { 
pArgs->button. style. notifyDetail = true; 
pArgs->button. style. contact = bsContact Toggle ; 
pArgs->button. style. feedback = bsFeedbackDecorate; 
pArgs->button . style . of f Decoration = 

lsDecorationNonExclusiveOff ; 
pArgs->button . style . onDecoration = 
lsDecorationNonExclusiveOn; 
} 

msgControlGetDirty 

Passes back the dirty state of the control. 

Takes P_BOOLEAN, returns STATUS. 

Comments clsToggleTable responds by setting *pArgs up as a 32 bit collection of the results of sending 

msgControlGetDirty to its first 32 children. The result of the first (bottom) child is placed in bit 0, the 
second in bit 1 , and so on. 

The resulting *pArgs is undefined if the toggle table has more than 32 children. 



msgControlGetEnable 

Passes back whether the control is enabled. 

Takes P_BOOLEAN, returns STATUS. 

Comments clsToggleTable responds by setting *p Args up as a 32 bit collection of the results of sending 

msgControlGetEnable to its first 32 children. The result of the first (bottom) child is placed in bit 0, 
the second in bit 1, and so on. 

The resulting *pArgs is undefined if the toggle table has more than 32 children. 
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msgControlGetValue 

Passes back the value of the control. 

Takes P_TAG, returns STATUS. 

clsToggleTable responds by setting *pArgs up as a 32 bit collection of the results of sending 
msgControlGetValue to its first 32 children. The result of the first (bottom) child is placed in bit 0, the 
second in bit 1, and so on. 

The resulting *pArgs is undefined if the toggle table has more than 32 children. 

msgControlSetDirty 

Sets dirty state of the control. 

Takes BOOLEAN, returns STATUS. 

clsToggleTable treats the pArgs as a 32 bit collection of values to send via msgControlSetDirty to its 
first 32 children. The value of bit is sent to the first (bottom) child, bit 1 is sent to the second child, 
and so on. 

msgControlSetEnable 

Sets whether the control is enabled. 

Takes BOOLEAN, returns STATUS. 

clsToggleTable treats the pArgs as a 32 bit collection of values to send via msgControlSetEnable to its 
first 32 children. The value of bit is sent to the first (bottom) child, bit 1 is sent to the second child, 
and so on. 



msgControlSetValue 

Sets the value of the control. 

Takes TAG, returns STATUS. 

Comments clsToggleTable treats the pArgs as a 32 bit collection of values to send via msgControlSetValue to its 

first 32 children. The value of bit is sent to the first (bottom) child, bit 1 is sent to the second child, 
and so on. 




in 
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ACETATE.H 



Interface file for the acetate. 

The functions described in this file are contained in INPUT.LIB. 

WARNING: Inking and the acetate layer are subject to major changes in future releases. 

#ifndef ACETATE_INCLUDED 
#define ACETATE_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

#ifndef GEO_INCLUDED 

#include <geo.h> 

#endif 

//prototypes 

AcetateTransform 

Converts coordinate to/from screen device root window and pen units. 

Returns void. 

Function Prototype void EXPORTED AcetateTransform( 

P_XY32 pXY, // coordinates to transform 

U16 type // for root-to-pen 

// 1 for pen-to-root 
); 

Comments Warning: This works only when transforming to or from the screen device root window. Other 

transforms must use drawing contexts. 



Function Protc 



AcetateCursorRequestVisible 

Used to request that the cursor turn on or off 

Returns void. 

void EXPORTED AcetateCursorRequestVisible ( 
BOOLEAN requestVisibleOn 
); 



Hutietion Pro? 



AcetateCursorThaw 

Unfreezes the cursor for pen movements. 

Returns STATUS. 

STATUS EXPORTED AcetateCursorThaw ( 
void 
); 
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AcetateCursorFreezePosition 

Freezes the cursor at the given Root window coordinate until the cursor image is reset to pNull 
(standard cursor). 

Returns STATUS. 

Function Prototype STATUS EXPORTED AcetateCursorFreezePosition ( 

P_XY32 pLoc // location in the root window 

); 



AcetateCursorXY 

Sets the cursor position. 

Returns void. 

Function Prototype void EXPORTED AcetateCursorXY ( 
COORD32 x, 
COORD32 y 

); 
AcetateCursorlmage 

Sets the cursor image. 

Returns STATUS. 

Function Prototype STATUS EXPORTED AcetateCursorlmage ( 
P_UNKNOWN pNewCursor, 
BOOLEAN sticky 

); 
Comments If pCursor == pNull, resets to the pen cursor and frees the substitute cursor memory. 



AcetateCursorUpdatelmage 

Updates the current cursor image. 

Returns STATUS. 

function Prototype STATUS EXPORTED AcetateCursorUpdatelmage ( 
P_UNKNOWN pNewCursor 
); 

Comments This interface should only be used for cursor animations and not to change the actual cursor to a 

different style. 

AcetateClear 

Clears (makes transparent) the entire acetate plane. 

Returns void. 

ictlon Prototype void EXPORTED AcetateClear ( 
void 
); 



AcetateClearDisable 

Used while grabbing to keep the acetate from being cleared. 
Returns void. 
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Function Prototype void EXPORTED AcetateClearDisable ( 
void 
); 

Comments Call it during input event processing and return one of the grab status returnValues. While the Clear 

Disable is active, calls to AcetateClear 

will have no effect. Calls to AcetateClearRect will still work however. 



AcetateClearRect 

Clears (makes transparent) the indicated acetate rect. pNull implies the entire plane. 

Returns void. 

void EXPORTED AcetateClearRect ( 
P_RECT32 pRect 
); 
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ANIMSP.H 



This file contains the API definitions for clsAnimSPaper. 

clsAnimSPaper inherits from clsSPaper. 

Records pen strokes and plays them back at a reduced speed. Provides settable speed, interstroke delay, 
line attribute and scaling parameters. 

Introduction 

clsAnimSPaper "animates" the drawing of scribbles by painting a few points, then pausing for the 
specified number of milliseconds before continuing. The animated playback is performed in a separate 
task, so playbacks will not disturb other events on the screen. A semaphore is used internally to prevent 
multiple tasks from painting in the AnimSPaper window simultaneously. The painting task is created 
whenever playback starts, and terminated when it finishes. 

The animation behavior is triggered by msgWinRepaint—that is, whenever the AnimSPaper is asked to 
paint itself. This means that you'll get slow, "animated" painting regardless of the cause of the 
msgWinRepaint: layout, resize, scrolling, unclipping, and so forth. If you want slow painting only 
under certain circumstances (e.g., when the user taps a button), set the Delay and Interstroke parameters 
to 0, then do this: 

0S_MILLI SECONDS om; 

om = yourDelay; 

ObjectCall(msgAnimSPaperSetDelay, animSPaper Instance, &om) ; 

om = yourlnterstroke; 

ObjectCall(msgAnimSPaperSetInterstroke, animSPaperlnstance, &om) ; 

ObjectCall(msgWinDirtyRect, animSPaperlnstance, NULL); 

ObjectCall(msgWinUpdate, animSPaperlnstance, NULL) ; 

om = 0; 

ObjectCall(msgAnimSPaperSetDelay, animSPaperlnstance, &om) ; 

ObjectCall(msgAnimSPaperSetInterstroke, animSPaperlnstance, &om) ; 

clsAnimSPaper Parameters 

There are four gettable/settable parameters having to do with scribble redisplay. Delay specifies the 
number of milliseconds to wait between painting line segments. It varies in inversely with the animation 
speed. Interstroke delay is a separate delay to be used between scribble strokes. It simulates the writer 
lifting and moving the pen from the end of one stroke to the beginning of the next. Line sets the 
thickness and other attributes used in playing back the scribble. Generally you shouldn't need to set 
anything except thickness. Scale affects the size of the scribbles when they're played back. The scale 
parameters will stretch/ compress the scribble along the x and y axes, also scaling the scribble's distance 
from the lower-left corner (0,0). This is especially useful for applications which wish to scale in 
proportion to the system font size. Note that since scribble scaling is in proportion to the original 
scribble, you may need to save what the system font size was when the scribble was recorded. 
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Pjr Other Facilities 

If pArgs->animSPaper.sendDone is true, an AnimSPaper will send msgAnimSPaperDone to its client 
when the animation is completed. 

For convenience two messages are provided to read and write scribbles to/from resource files. 

►^ Note on Delay and Interstroke Parameters 

AnimSPaper uses OSTaskDelayO to create the Delay and Interstroke delay. The minimum increment of 
OSTaskDelay is a system tick (systick), whose length is device dependent. Use OSSystemInfo() to find 
the length of a systick (see OS.H for details). On an average PC or 386 system the systick is 55 
milliseconds, or about an eighteenth of a second. So micro-adjustments of Delay and Interstroke from, 
say, 60 milliseconds to 80 milliseconds will be ineffective. 

Pjr Debugging Flags 

clsAnimSPaper uses the Handwriting debug flag set 'Z'. clsAnimSPaper uses: 
80000 Show all internal debugging messages 



tifndef ANIMSP_INCLUDED 
tdefine ANIMSP_INCLUDED 

tinclude <spaper.h> // ancestor flags 
♦include <sysgraf.h> // line & scale def ns 
tinclude <fs.h> // filing def'ns 



tifndef SPAPER_INCLUDED 

tendif 

tifndef SYSGRAF_INCLUDED 

tendif 

tifndef FS_INCLUDED 

tendif 



r Common #defines and typedefs 



typedef struct ANIM_SPAPER_NEW_ONLY { 

SYSDC_LINE line; // line attributes for scribble playback 
0S_MILLISEC0NDS delay; // delay between stroke segments on playback 

// (inverse of playback speed) 
0S_MILLISEC0NDS interstroke; // delay between strokes on playback 
OBJECT client; // recipient of msgAnimSPaperDone 
BOOLEAN sendDone; //if TRUE, animSPaper will send client 

// msgAnimSPaperDone when animation's done 
SCALE scale; // how much larger or smaller to scale the 

// scribble when it's played back. (1,1) 

// plays back at same scale as recorded. 
S32 sparel; // unused (reserved) 

S32 spare2; // unused (reserved) 

} ANIM_SPAPER_NEW_ONLY, *P_ANIM_SPAPER_NEW_ONLY; 

tdefine animSPaperNewFields \ 
sPaperNewFields \ 

ANIM_SPAPER_NEW_ONLY animSPaper; 

typedef struct ANIM_SPAPER_NEW { 

animSPaperNewFields 
} ANIM SPAPER NEW, *P ANIM SPAPER NEW; 
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Messages 



hessage 
irgymenfs 



Comments 



msgNew 

Creates an AnimSPaper window. 

Takes P_ANIM_SPAPER_NEW, returns STATUS. Category: class message. 

typedef struct ANIM_SPAPER_NEW { 

animSPaperNewFields 
} ANIM SPAPER NEW, *P ANIM SPAPER NEW; 



The fields you commonly set are: 

pArgs->animSPaper . line . thickness : 
pArgs->animSPaper . delay : 
pArgs->animSPaper . interstroke : 
pArgs->animSPaper . client : 
pArgs->animSPaper . sendDone : 
pArgs->animSPaper . scale : 



thickness of line on playback 

inverse of animation speed 

delay between strokes 

whom to notify when animation is done 

whether to notify client 

playback size relative to input size 



Comments 



Arguments 



msgNewDefaults 

Initialize pArgs. 

Takes P_ANIM_SPAPER_NEW, returns STATUS. Category: class message. 

typedef struct ANIM_SPAPER_NEW { 

animSPaperNewFields 
} ANIM SPAPER NEW, *P ANIM SPAPER NEW; 



Sets: 



pArgs->animSPaper . line . cap 
pArgs->animSPaper . line . join 
pArgs->animSPaper . line . thickness 
pArgs->animSPaper . line .miterLimit 
pArgs->animSPaper . line . radius 
pArgs->animSPaper .delay 
pArgs->animSPaper . interstroke 
pArgs->animSPaper . client 
pArgs->animSPaper. sendDone 
pArgs->animSPaper . scale . x 
pArgs->animSPaper . scale . y 
pArgs->sPaper . flags 



pArgs->win . flags . input 



= sysDcCapRound; 
= sysDcJoinRound; 
= 6; 
= 10; 
= 0; 
= 40; 
= 160; 
= objNull; 
= TRUE; 

= FxIntToFx(l); 
= FxIntToFx(l) ; 
&= (-spScribbleEdit 

& ~spRedisplay 

& ~spVRuling 

& ~spRuling 

& ~spBackground) ; 
|= input InkThrough; 



msgAnimSPaperReadScribble 

Reads a scribble from a resource file, sets it into the AnimSPaper and displays it. 

Takes P_ANIM_SPAPER_SCPJBBLE, returns STATUS. Category: class message, 
tdefine msgAnimSPaperReadScribble MakeMsg (clsAnimSPaper, 1) 

typedef struct ANIM_SPAPER_SCRIBBLE { 

FS_LOCATOR locator; // resource file locator 
RES_ID resld; // resource id for the scribble 

} ANIM SPAPER SCRIBBLE, *P ANIM SPAPER SCRIBBLE; 
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msgAnimSPaperWriteScribble 

Writes the AnimS Paper's current scribble to a resource file. 

Takes P_ANIM_SPAPER_SCRIBBLE, returns STATUS. Category: class message. 

#define msgAnimSPaperWriteScribble MakeMsg(clsAnimSPaper, 2) 

Message typedef struct ANIM_SPAPER_SCRIBBLE { 

Arguments FS_LOCATOR locator; // resource file locator 

RES_ID resld; // resource id for the scribble 

} ANIM_SPAPER_SCRIBBLE, *P_ANIM_SPAPER_SCRIBBLE; 

msgAnimSPaperSetDelay 

Specifies delay for scribble playback 

Takes P_OS_MILLISECONDS, returns STATUS. Category: class message. 

tdefine msgAnimSPaperSetDelay MakeMsg(clsAnimSPaper, 4) 



msgAnimSPaperGetDelay 

Passes back delay for scribble playback 

Takes P_OS_MILLISECONDS, returns STATUS. Category: class message. 

#define msgAnimSPaperGetDelay MakeMsg(clsAnimSPaper, 5) 

msgAnimSPaperSetlnterstroke 

Specifies interstroke delay for scribble playback 

Takes P_OS_MILLISECONDS, returns STATUS. Category: class message. 

#define msgAnimSPaperSetlnterstroke MakeMsg(clsAnimSPaper, 6) 



msgAnimSPaperGetlnterstroke 

Passes back interstroke delay for scribble playback 

Takes P_OS_MILLISECONDS, returns STATUS. Category: class message. 

tdefine msgAnimSPaperGetlnterstroke MakeMsg(clsAnimSPaper, 7) 



msgAnimSPaperSetLine 

Specifies line attributes for scribble playback 

Takes P_SYSDC_LINE, returns STATUS. Category: class message. 

#define msgAnimSPaperSetLine MakeMsg(clsAnimSPaper, 8) 

msgAnimSPaperGetLine 

Passes back line attributes for scribble playback 

Takes P_SYSDC_LINE, returns STATUS. Category: class message. 

tdefine msgAnimSPaperGetLine MakeMsg(clsAnimSPaper, 9] 
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Notifications 



msgAnimSPaperSetScale 

Specifies scaling for scribble playback. 

Takes P_SCALE, returns STATUS. Category: class message. 

#define msgAnimSPaperSetScale MakeMsg(clsAnimSPaper, 11) 

Comments The scribble will be played back at a SCALE relative to the size at which it was recorded. X and Y scales 

may be set independently. The SCALE affects both the scribble and its distance from the lower-left 
corner (0,0). 



msgAnimSPaperGetScale 

Passes back scaling for scribble playback 

Takes P_SCALE, returns STATUS. Category: class message. 

tdefine msgAnimSPaperGetScale MakeMsg(clsAnimSPaper, 12) a. 

Notifications 

msgAnimSPaperDone 

Sent to client when animation is complete. 

Takes OBJECT, returns STATUS. Category: advisory message. 

#define msgAnimSPaperDone MakeMsg(clsAnimSPaper, 3) 

intents pArgs is the animSPaper's UID. This message is sent only if there is a client and 

pArgs->animSPaper.sendDone was true at msgNew time. 
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GWIN.H 



This file contains the API definition for clsGWin. 
clsGWin inherits from clsWin. 



Introduction 

clsGWin provides a convenient default implementation of several important PenPoint features ~ gesture 
and keyboard processing, quick help interaction and event forwarding. 

clsGWin is an ancestor of many of PenPoint's window-based classes, including all of the Toolkit classes. 

Many tasks involving the input system and the handwriting recognition system can be handled very 
simply using only a few clsGWin messages. Some tasks require use of some of clsGWin's more 
sophisticated messages. And there are some task for which clsGWin is not appropriate. For instance, 
even a modest drawing application or "ink editor" will almost certainly have to interact more directly 
with the input system and handwriting recognition system. 

Several important task can be accomplished by using just few clsGWin messages: 



To process gestures, see msgGWinGesture. 

To process keyboard input, see msgGWinKey. 

To implement quick help, use gWin's helpld; see GWIN_NEW_ONLY and msgGWinSetHelpId. 

To process gestures and keyboard events which occurred in child windows, see 
msgGWinForwardedGesture or msgGWinForwardedKey. 

♦ To control whether or not a window responds to gestures, see the gestureEnable field in 
GWIN_STYLE. 

More complex subclasses will need to understand more details, as described below. 



Debugging Flags 



GWin's debugging flag set is '#' (0x23). Defined flags are: 
0001 Display generally useful messages. 
0004 Display messages during quick help processing. 
0010 Display messages during timeout processing. 



Keyboard Processing 



Keyboard processing and forwarding occurs when a gWin receives msglnputEvent with a key event 
message in pArgs->devCode. The steps taken are: 

♦ gWin self sends msgGWinKey with the event. 
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♦ IF the response to msgGWinKey is stsRequestDenied, gWin self sends msgGWinBadKey. gWin's 
default response to msgGWinKey is to return stsRequestForward, which causes gWin to perform 
key event forwarding. 

♦ If the response to msgGWinKey is stsRequestForward and style.keyboardForward is set, gWin self 
sends msgGWinForwardKey. In response to this message, the gWin packages up the data and uses 
msgWinSend to forward the key information. This results in parent windows potentially receiving 
msgGWinForwardedKey (see msgGWinForwardedKey description). gWin's default response to 
msgGWinForwardedKey is to return stsRequestForward, which causes the event forwarding to 
continue. 

♦ If the response to msgGWinForwardKey is stsRequestDenied or stsRequestForward, gWin self 
sends msgGWinBadKey. 

Gesture Processing 

A gWin self sends msgGWinGesture when one of the following occurs. (Each of these is described more 
detail below.) 

♦ Case 1: A gWin receives msgGWinXList (typically because a translation has completed). 

♦ Case 2: A gWin receives msglnputEvent with an event of press-hold or a tap-press-hold. 

♦ Case 3: A gWin receives msgQuickHelpHelpShow from theQuickHelpManager. 

If the response to msgGWinGesture is stsRequestDenied, the gesture is unrecognized and one of the 
following actions is taken: 

♦ In Case 1, a translated gesture, msgGWinBadGesture is self sent. 

♦ In Case 2, normal gesture processing continues. This is because a press-hold or a tap-press-hold 
gesture is sent in response to an input event while potentially in the process of collecting data for 
another gesture (see below). 

♦ In Case 3, the "no help available" help is displayed via msgQuickHelpShow. 

If the response to msgGWinGesture is stsRequestForward, msgGWinForwardGesture is self sent. If 
the response to msgGWinForwardGesture is stsRequestDenied or stsRequestForward, the same action 
is taken as if msgGWinGesture returned stsRequestDenied. 

Case 1 : How a GWin Receives Translated Gestures. 

msgGWinGesture is self sent in response to msgGWinXList. msgGWinXList is self sent by gWin after 
an xGesture translator has completed its translation. This occurs as follows: 

When msgPenStroke is received from the input system, the gWin adds strokes to a gesture translator. 
This is done via a self send of msgGWinStroke, which adds the stroke via sending msgScrAddStroke to 
the gesture translator. 

gWin --> msgScrAddStroke --> xGesture Translator 

When an "out of proximity" event is received, gWin self sends msgGWinComplete. In response to the 
msgGWinComplete, gWin sends msgScrComplete to the gesture translator. 

gWin --> msgScrComplete --> xGesture Translator 

The translator then sends msgXlateCompleted back to the gWin, indicating translation is complete. 
GWin retrieves translated results by sending msgXlateData to the gesture translator. 
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gWin <-- msgXlateCompleted <-- xGesture Translator — > msgXlateData — > xGesture 

Translator 

This returns an xlist containing the translated data (see xlist.h). GWin then self sends msgGWinXList 
to process the xlist. This extracts the appropriate information from the xlist (viaXList2Gesture). gWin 
then performs the gesture processing and forwarding described below: 

♦ Self send msgGWinGesture. 

♦ If msgGWinGesture returns stsRequestDenied, gWin self sends msgGWinBadGesture. 

♦ If msgGWinGesture returns stsRequestForward and style.gestureForward is set, gWin self sends 
msgGWinForwardGesture. Similar to the forwarding of keyboard events, the gWin packages up 
the gesture information and uses msgWinSend to forward the gesture. This results in parent 
windows potentially receiving msgGWinForwardedGesture (see msgGWinForwardedGesture). 

♦ If msgGWinForwardGesture returns stsRequestForward and the gesture is the help gesture, gWin 
calls PenPoint's quick help with hlpQuickHelpNoHelp. This invokes quick help with the "No help 
available" text. 

♦ If msgGWinForwardGesture returns stsRequestDenied or stsRequestForward, gWin self sends 
msgGWinBadGesture 

Case 2: How a GWin Synthesizes Some Gestures. 

If, when processing input events, gWin sees a press-hold or a tap-press-hold input event, gesture 
processing and forwarding takes place. If the gesture is unrecognized, then normal input processing 
continues. This means that if an end-user press-holds on an area where press-hold has no meaning, the 
window in question receives msgGWinGesture with xgsPressHold. The window returns 
stsRequestForward (as will all the windows that see msgGWinForwardGesture). Normal processing 
continues, and when the user lifts the pen the translation of the single tap occurs and the gesture 
processing mentioned above takes place. If the gesture is recognized, the gesture translation is aborted 
and input data is thrown away until (and including) the next Pen Up event. A description: 

♦ gWin self sends msgGWinGesture with xgsPressHold or xgsTapHold. 

♦ If the response to msgGWinGesture is stsRequestDenied, processing of the input continues. 

♦ If the response to msgGWinGesture is stsOK, gesture processing is aborted. 

♦ If the response to msgGWinGesture is stsRequestForward and style.gestureForward is set, gWin 
self sends msgGWinForwardGesture. This results in parent windows potentially receiving 
msgGWinForwardedGesture (see msgGWinForwardedGesture). 

♦ If the response to msgGWinForwardGesture is stsRequestDenied or stsRequestForward, 

processing of the input continues. 

♦ If the response to msgGWinForwardGesture is stsOK, gesture processing is aborted. 

Case 3: How a GWin Responds to msgQuickHelpHelpShow. 

The final case in which msgGWinGesture is sent is in response to msgQuickHelpHelpShow. This is 
sent from theQuickHelpManager when in help mode and the user taps on the screen. GWin responds 
by sending msgGWinGesture with the help gesture, and performing similar forwarding above. When 
msgGWinGesture returns stsRequestDenied, or msgGWinForwardGesture returns stsRequestDenied 
or stsRequestForward, gWin sends msgQuickHelpShow to display the No Help Available message. 
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style.gesture Local and Coordinate Transformations 

When using large windows (width or height near or above 2 A 16), you should style.gestureLocal to true. 
Doing so avoids some potential numeric overflow conditions that can make gesture recognition 
unreliable. 

Setting style.gestureLocal true changes the coordinate system used internally by gWin. It also changes 
the coordinate system used in some of gWin's more sophisticated self sent messages. If you don't use 
these more sophisticated messages, you can just set style.gestureLocal true and never worry about it 
again, regardless of the size of your window. If you do use these messages, then you should read the rest 
of this section to understand what's different. 

Here are the messages whose parameters are affected by style.gestureLocal: 

♦ msgGWinStroke 

♦ msgGWinXList 

♦ msgGWinTransformGesture 

♦ msgGWinTransformXList 

Normal gesture processing (style.gestureLocal is false) is done using the following coordinate 
transformations: 

♦ The stroke input event is delivered with pArgs->xy set to the local window coordinates and the pen 
data in root window pen coordinates. 

♦ On the first stroke to the window, gWin remembers an offset of (0,0). This step is obviously trivial 
in this case but is important when style.gestureLocal is true. 

♦ This value is first converted to root window coordinates and then the resulting value is converted to 
pen units. 

♦ This vector is subtracted from the origin of the pen stroke data. The pen stroke data is still in pen 
units but has been shifted so that its origin is relative to the local window origin. 

♦ This shifted stroke is self sent using msgGWinStroke. THIS IS IMPORTANT. Any object 
intercepting this message gets pen data that has been shifted to appear in the local window. This is 
slightly different than the pen stroke which comes from the input system. 

♦ In response to the first msgGWinStroke, gWin creates a translator and makes itself an observer of 
the translator. The stroke is then added to the translator. 

♦ Normal input collection of strokes continues. Eventually the gesture is completed and translation 
occurs. 

♦ In response to msgXlateComplete, gWin gets the XList data and converts it from pen units to 
window units. Remember that since the pen strokes were shifted by the origin of the window (in 
digitizer units), the window units give locations in the local window. gWin then self sends 
msgGWinXList. 

♦ In response to msgGWinXList, gWin converts the xlist information and self sends 
msgGWinGesture. 

If style.gestureLocal is true, the same sequence of events occurs, but with the following change in 
coordinate systems: 

♦ When the first stroke comes in to the gWin, the local window coordinates of the stroke are saved as 
the offset instead of 0,0. This value is converted to root window coordinates and then converted to 
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pen units and used to offset the stroke. This means that the stroke is no longer in local window 
space, but rather are in root window coordinate space. 

♦ Subclasses which handle msgGWinStroke are getting data which is root window relative. If they 
need it in local window space then they have to transform it first. 

♦ When the translation is complete, the offset that was remembered earlier is converted to root 
window coordinates and then to pen units. This offset is added to the points returned by the 
translator before converting back to screen units. The effect is that now the gesture is shifted back to 
its proper location in root window space. 

♦ When converting the XList data to the GWin gesture, the important points are converted from root 
window coordinates back to local window coordinates before self sending msgGWinGesture. 

#ifndef GWIN_INCLUDED 
#define GWIN_INCLUDED 

tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 

tifndef CLSMGR_INCLUDED 
tinclude <clsmgr.h> 
tendif 

tifndef WIN_INCLUDED 
tinclude <win.h> 
tendif 

// Next up: 25 Recycled: 3 



Common #defines and typedefs 



typedef OBJECT GWIN; 

Default Window Flags 

These are the default input flags set by a gWin at msgNew time if gestureEnable is set. Changing these 
flags after new time is possible, but extreme care needs to be taken as these define the pen events that get 
generated to the window. 

tdefine gWinlnputFlags (input Stroke | inputOutProx | \ 

inputlnk | inputTip | inputTimeout | inputAutoTerm | \ 
inputEnter | inputHoldTimeout) 



Style Structure 



typedef struct GWIN_STYLE { 

U16 gestureEnable: 1, 

gestureForward: 1, 

gestureLocal : 1, 

keyboardForward: 1, 

privateDatal : 2, 

grabDown : 1 , 

grabActive: 1, 

firstEnter: 1, 

tossingEvents: 1, 

askOtherWin: 1, 

otherWinSaysYes : 1 , 

reserved: 4; 
} GWIN STYLE, *P GWIN STYLE; 



// enables gesture translation 

// enables forwarding of gestures 

// enables localized strokes for large 

// gesture windows (>32K digitizer pts) 

// enables forwarding of key events 

// private 

// grab input on msgPenDown vs. 

// msgPenStroke 

// private 

// grab on msgPenEnter if no other grab 

// private 

// ask other gWin if it wants event 

// answer yes if asked if you want event 

// reserved for future use 



642 PENPOINT API REFERENCE 

Part 5 / Input and Handwriting 

Gesture Structure 

This data structure defines all information returned, by a gesture translator in the form of a simple data 
structure. It is used as a parameter to many of the gesture methods defined in gWin. 

typedef struct GWIN_GESTURE { 

// gesture Id 

// bounding box in LWC 

// gesture hot point 

// object in which the gesture was generated 

// reserved for future use 
} GWIN GESTURE, *P GWIN GESTURE; 



MESSAGE 


msg; 


RECT32 


bounds ; 


XY32 


hotPoint ; 


OBJECT 


uid; 


U32 


reserved; 



Messages 



msgNew 

Creates and initializes a new instance. 

Takes P_GWIN_NEW, returns STATUS. Category: class message. 

typedef struct GWIN_NEW_ONLY { 

GWIN_STYLE style; // gWin style flags 

U32 helpld; // quick help id 

U32 reserved; 
} GWIN_NEW_ONLY, *P_GWIN_NEW_ONLY; 

#define gWinNewFields \ 

winNewFields \ 

GWIN_NEW_ONLY gWin; 

typedef struct GWIN_NEW { 

gWinNewFields 
} GWIN_NEW, *P_GWIN_NEW; 

If gWin.style.gestureEnable is true, then gWin ORs in gWinlnputFlags into pArgs->win.flags.input 
before passing the message to its ancestors. These win.flags.input bits can be changed after the gWin is 
created, but extreme care should be taken! 

If setting a helpld, setting the pNew->gWin.helpId to the same as the pNew->win.tag helps minimize 
memory needed by the object. It is recommended that the helpld be the same as the window tag if 
possible. However, if the window tag changes when the help id is the same as the window tag, then the 
help tag will change too. 

msgNewDefaults 

Initializes the GWIN_NEW structure to default values. 

Takes P_GWIN_NEW, returns STATUS. Category: class message. 

typedef struct GWIN_NEW { 

gWinNewFields 
} GWIN_NEW, *P_GWIN_NEW; 

Zeros out pNew->gWin and sets: 

pArgs->gWin. style. gestureEnable = TRUE; 
pArgs->gWin. style. gestureForward = TRUE; 
pArgs->gWin. style. keyboardForward = TRUE; 
pArgs->gWin. style. grabDown = TRUE; 
win. input = gWinlnputFlags; 



GWIN.H 
Message* 



643 



Message 
Arguments 



msgGWinGetStyle 

Returns the current style. 

Takes P_GWIN_STYLE, returns STATUS. 

#define msgGWinGetStyle 

typedef struct GWIN STYLE { 



U16 gestureEnable : 


1, 


// 


gestureForward: 


1, 


// 


gestureLocal : 


1, 


// 
// 


keyboardForward : 


1, 


// 


privateDatal : 


2, 


// 


grabDown : 


1, 


// 
// 


grabActive : 


1, 


// 


firstEnter: 


1, 


// 


tossingEvents: 


1, 


// 


askOtherWin : 


1, 


// 


otherWinSaysYes : 


1, 


// 


reserved: 


4; 


// 


} GWIN_STYLE, *P_GWIN_STYLE 


/' 





MakeMsg(clsGWin, 12) 



enables gesture translation 

enables forwarding of gestures 

enables localized strokes for large 

gesture windows (>32K digitizer pts) 

enables forwarding of key events 

private 

grab input on msgPenDown vs. 

// msgPenStroke 

// private 

grab on msgPenEnter if no other grab 

private 

ask other gWin if it wants event 

answer yes if asked if you want event 

reserved for future use 



Message 
Arguments 



Comments 



msgGWinSetStyle 

Sets the style settings. 

Takes P_GWIN_STYLE, returns STATUS. 

#define msgGWinSetStyle 



U16 gestureEnable: 


1, 


II 


gestureForward : 


1, 


II 


gestureLocal: 


1, 


II 
II 


keyboardForward : 


1, 


II 


privateDatal : 


2, 


II 


grabDown : 


1, 


II 
II 


grabActive: 


1, 


II 


firstEnter: 


1, 


II 


tossingEvents: 


1, 


II 


askOtherWin: 


1, 


II 


OtherWinSaysYes : 


1, 


II 


reserved: 


4; 


II 


} GWIN STYLE, *P GWIN STYLE 


I 





MakeMsg(clsGWin, 13) 



enables gesture translation 

enables forwarding of gestures 

enables localized strokes for large 

gesture windows (>32K digitizer pts) 

enables forwarding of key events 

private 

grab input on msgPenDown vs. 

msgPenStroke 

private 

grab on msgPenEnter if no other grab 

private 

ask other gWin if it wants event 

answer yes if asked if you want event 

reserved for future use 



If gestureEnable is true, gWin ORs in the gWinlnputFlags with the window flags. (See the comments 
near msgNew in this file.) Setting gestureEnable to false does NOT clear these flags. 



msgGWinSetHelpId 

Sets the gWin's helpld for quick help. 

Takes U32, returns STATUS. 

#define msgGWinSetHelpId MakeMsg(clsGWin, 16) 

Comments Setting the helpld to be identical to the gWin's win.tag helps minimize the amount of instance data 

taken by a gWin. 
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msgGWinGetHelpId 

Returns the gWin's helpld. 

Takes P_U32, returns STATUS. 

#define msgGWinGetHelpId MakeMsg(clsGWin, 17) 



msgGWinGe£Translator 

Returns the gWin's translator object. 

Takes P_OBJECT, returns STATUS. 

fdefine msgGWinGetTranslator MakeMsg(clsGWin, 7) 

snts gWin's default response is to return the current translator object. 

By default, gWin has a null current translator unless strokes have been added since msgNew or since the 
last msgGWinAbort or msgGWinComplete. (In other words, gWin does not have a translator unless it 
is currently collecting or translating strokes.) 

o msgGWinAbort 

msgGWinSetTranslator 

Sets the translator object and returns the previous one. 

Takes P_OBJECT, returns STATUS. 

#define msgGWinSetTranslator MakeMsg(clsGWin, 8) 

juts This message has no affect if the gWin has not received a stroke from the input system since the last 

msgGWinComplete or msgGWinAbort. 

Because of this limitation you probably should not use this message. 

gWin's default response is to set its translator object to pArgs AND to set *pArgs to the uid of the 
previous translator. 

© msgGWinAbort 



msgGWinTransformGesture 

Transforms gesture information into local window coordinates. 

Takes P_GWIN_GESTURE, returns STATUS. 

tdefine msgGWinTransformGesture MakeMsg(clsGWin, 14) 

typedef struct GWIN_GESTURE { 

MESSAGE msg; // gesture Id 

RECT32 bounds; // bounding box in LWC 

XY32 hotPoint; // gesture hot point 

OBJECT uid; // object in which the gesture was generated 

U32 reserved; // reserved for future use 
} GWIN_GESTURE, *P_GWIN_GESTURE ; 

This message is useful for clients who handle msgGWinForwardedGesture. 

Transforms the gesture bounds and hotPoint into the local window coordinate system. 

This is only necessary if the gesture occurred in a window other then self. 

gWin's default response modifies the bounds, hotPoint, and uid (set to self) fields. 



GWIN.H 
Gesture Processing 



645 



msgGWinTransformXList 

Transforms xlist information to local window coordinates. 

Takes P.XLIST, returns STATUS. 

tdefine msgGWinTransformXList MakeMsg(clsGWin, 15) 

Comments This message is useful for clients who handle msgGWinXList. 

This message is only necessary if the xlist was generated relative to a window other then self. This 
message transforms the gesture bounds and hotPoint to local window coordinates system. 



^Gesture Processing 



msgGWinStroke 

Self sent to process a pen stroke received from the input system. 

Takes P_INPUT_EVENT, returns STATUS. 

#define msgGWinStroke MakeMsg(clsGWin, 5) 

Comments If style. gestureEnable is false, gWin's default response is to return stsOK. 

If style.gestureEnable is true, gWin's default response is as follows. First, if the gWin has no translator, 
one is created by self sending msgGWinTranslator and gWin makes itself an observer of the translator. 
Next It then sends msgScrAddedStroke to the translator to tell the translator that the gWin has received 
a new stroke. 

Subclasses can handle this message and process individual strokes. If style.gestureLocal is false, stroke 
coordinates are self relative; if style.gestureLocal is true, stroke coordinates are root window relative. 

See Also msgGWinTranslator 

msgGWinTranslator 

Self sent to retrieve the translator used to gather and translate strokes. 

Takes P_OBJECT, returns STATUS. 

tdefine msgGWinTranslator MakeMsg(clsGWin, 4) 

Comments gWin's default response is to create an instance of clsXGesture. 

gWin self sends msgGWinTranslator whenever it needs a translator to gather and translate strokes. For 
instance, when gWin receives msgGWinStroke, and the stroke is the first stroke in a new gesture, gWin 
self sends msgGWinTranslator. 

The translator will be destroyed during gWin's handling of msgGWinComplete or msgGWinAbort. 

See Also msgGWinComplete 



msgGWinComplete 

Self sent to complete a gesture. 

Takes void, returns STATUS. 

tdefine msgGWinComplete MakeMsg(clsGWin, 6) 

Comments gWin self sends msgGWinComplete when "out of proximity" or a timeout occurs. Clients can send 

msgGWinComplete to cause gesture completion and translation. 
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gWin s default response to is cause translation as described in the introductory material at the beginning 
of this file. gWin then destroys its translator. 

If the gWin has a grab (perhaps because it was collecting strokes when a client sends this message), the 
grab is NOT terminated in response to this message. But the gWin will remember that this message has 
been received and will terminate the grab in response to the next msglnputEvent it receives. 



msgGWinAbort 

Aborts a gesture. 

Takes void, returns STATUS. 

tdefine msgGWinAbort MakeMsg(clsGWin, 9) 

Comments gWin s default response is very similar to its response to msgGWinComplete, except that the translation 

is aborted instead completed. As with msgGWinComplete, the gWin destroys its translator and ceases 
collecting strokes. 

A client can send msgGWinAbort to abort the gWin's processing of a gesture. 

The grab behavior is identical to that described with msgGWInComplete. 

Subclasses may field msgGWinAbort but must also allow their ancestor to see the message. 

msgGWinXList 

Self sent by gWin to process an xlist. 

Takes P_XLIST, returns STATUS. 

#define msgGWinXList MakeMsg(clsGWin, 1) 

Comments After a translation has been completed (in other words, after gWin has received msgXlateCompleted 

from its translator), gWin extracts the translation data (in the form of an xlist) from the translator, and 
then self sends msgGWinXList. 

gWin's default response is to extract the gesture information from the xlist (using the xlist utility routine 
XList2Gesture) and then self sends msgGWinGesture. 

See Also msgGWinGesture 



Gesture Recognition and Forwarding 
Messages 



msgGWinGesture 

Self-sent to process a gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

tdefine msgGWinGesture MakeMsg(clsGWin, 2) 

typedef struct GWIN_GESTURE { 



MESSAGE 


msg; 


// gesture Id 


RECT32 


bounds ; 


// bounding box in LWC 


XY32 


hotPoint; 


// gesture hot point 


OBJECT 


uid; 


// object in which the gesture was generated 


U32 


reserved; 


// reserved for future use 



} GWIN GESTURE, *P GWIN GESTURE; 
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Comments The default response to msgGWinGesture is as follows: 

For the help gesture(s), return the result of self sending msgGWinHelp. By default, msgGWinHelp 
returns stsRequestForward if the helpld is zero, or stsOK if there is a valid helpld. 

For all other gestures, return stsRequestForward. 

Effectively, the default response of gWin to msgGWinGesture is to return stsOK if the gesture is a help 
gesture on a window and the window has a valid helpld. Otherwise the default behavior is to return 
stsRequestForward. 

GWin's default response to msgGWinForwardedGesture is the same as msgGWinGesture. This means 
that the help gesture(s) is forwarded up the window hierarchy until a gWin has a valid helpld, and then 
that gWin sends the appropriate message and quick help id to theQuickHelpManager. 

Hence a window can have a common helpld (and corresponding help text) for all (or some) child 
windows, and the quick help text displayed will be the same regardless of the child window the gesture 
actually occurred in. 

3 
Q. 

Remm Value stsRequestForward The gesture was not processed and should be forwarded. z 

stsRequestDenied The gesture was not processed and should not be forwarded. 
stsOK The gesture was processed and should not be forwarded. 

See Also msgGWinXList 

msgGWinForwardGesture 

Causes a gesture to be forwarded to parent windows. 

Takes P_GWIN_GESTURE, returns STATUS. 

tdefine msgGWinForwardGesture MakeMsg(clsGWin, 20) 

Message typedef struct GWIN_GESTURE { 

Arguments MESSAGE msg; // gesture Id 

RECT32 bounds; // bounding box in LWC 

XY32 hotPoint; // gesture hot point 

OBJECT uid; // object in which the gesture was generated 

U32 reserved; // reserved for future use 
} GWIN_GESTURE, *P_GWIN_GESTURE; 

Comments Subclasses should not handle this message. 

In response to this message, gWin initiates gesture forwarding. This results in each parent window 
within the same process receiving msgGWinForwardedGesture, from the immediate parent to the root. 

If any window along the path returns stsOK from msgGWinForwardedGesture, or the window has 
style.gestureForward off, stsOK is returned. 

gWin performs this forwarding via msgWinSend. The status returned to the sender of 
msgGWinForwardGesture is the status returned by this msgWinSend. See the comments for 
msgGWinForwardedGesture for return values and their interpretation. 

The msgWinSend of msgGWinForwardedGesture is only delivered to windows in same process. 

Retwrn VaSye stsRequestForward The gesture was not processed by any of the ancestor windows. Further processing 

should occur if possible. 

stsRequestDenied The gesture was not processed by any of the ancestor windows, and was aborted at 
some level of the walk. No further processing should occur. 

stsOK The gesture was processed. No further processing should occur. 

See Mso msgGWinXList 
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msgGWinForwardedGesture 

Message received when a gesture is forwarded. 

Takes P_GWIN_GESTURE, returns STATUS. 

tdefine msgGWinForwardedGesture MakeMsg(clsGWin, 11) 

Message typedef struct GWIN_GESTURE { 

Arguments MESSAGE msg; // gesture Id 

RECT32 bounds; // bounding box in LWC 

XY32 hotPoint; // gesture hot point 

OBJECT uid; // object in which the gesture was generated 

U32 reserved; // reserved for future use 
} GWIN_GESTURE, *P_GWIN_GESTURE; 

Comments See the comments describing msgGWinGesture. 

msgGWinForwardedGesture is sent to a gWin when a gesture event has been forwarded from a child 
window. Subclasses wishing to process gestures forwarded from child windows should handle this 
message. 

Do not send this message; it should only be self sent by clsGWin. 
Return Value stsRequestForward The gesture was not processed and should be forwarded further. 

stsRequestDenied The gesture was not processed and should not be forwarded any further. 

stsOK The gesture was processed and should not be forwarded any further. 
See Also msgGWinHelp 

msgGWinBadGesture 

Displays feedback for unrecognized and unknown gestures. 

Takes P_GWIN_GESTURE, returns STATUS. 

#define msgGWinBadGesture MakeMsg (clsGWin, 10) 

Messoge typedef struct GWIN_GESTURE { 

Arguments MESSAGE msg; // gesture Id 

RECT32 bounds; // bounding box in LWC 

XY32 hotPoint; // gesture hot point 

OBJECT uid; // object in which the gesture was generated 

U32 reserved; // reserved for future use 
} GWINJ3ESTURE, *P_GWIN_GESTURE; 

Comments gWin's response is to display the unrecognized gesture feedback (if pArgs->msg == xgsNull) or the 

unknown gesture feedback (for any other value of pArgs->msg). 

gWin's default response to msgGWinXList includes self-sending msgGWinBadGesture if the gesture is 
unrecognized by the recognition system (xgsNull) or if none of the recipients of msgGWinGesture and 
msgGWinForwardedGesture processed the gesture. 

See Ab© msgGWinXList 

msgGWinHelp 

The gWin displays quick help for itself. 

Takes NULL, returns STATUS. 

#define msgGWinHelp MakeMsg (clsGWin, 22) 
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Comments If the gWin s helpld is 0, gWIn returns stsRequestForward. Otherwise, gWin sends 

msgQuickHelpShow to theQuickHelpManager with the gWin s help id. 

Return Volue stsRequestForward The helpld of self is 0. 

stsOK Quick help was invoked for self. 

ird Processing and 
Forwarding Messages 

msgGWinKey 

Self sent to process a key input event. 
Takes P_INPUT_EVENT, returns STATUS. 

♦define msgGWinKey MakeMsg(clsGWin, 21) 2 

z 
Comments As part of its default response to msglnputEvent, gWin self sends msgGWinKey if the input event is a 

key event. 

gWin's default response to msgGWinKey is to return stsRequestForward. 

Return Vatye stsRequestForward The key event was not processed and should be forwarded further. 

stsRequestDenied The key event was not processed and should not be forwarded any further. 
stsOK The key event was processed and should not be forwarded. 

msgGWinForwardKey 

Initiates keyboard event forwarding. 

Takes P_INPUT_EVENT, returns STATUS. 

tdefine msgGWinForwardKey MakeMsg(clsGWin, 19) 

Comments Subclasses should not handle this message. 

In response this message, gWin initiates keyboard event forwarding. This results in each parent window 
within the same process receiving msgGWinForwardedKey, from the immediate parent to the root. 

If any window along the path returns stsOK from msgGWinForwardedGesture, or the window has 
style.keyboardForward off, stsOK is returned. 

gWin performs this forwarding via msgWinSend. The status returned to the sender of 
msgGWinForwardKey is the status returned by this msgWinSend. See the comments for 
msgGWinForwardedKey for return values and their interpretation. 

The msgWinSend of msgGWinForwardedKey is only delivered to windows in same process. 

Return ¥«lye stsRequestForward The key event was not processed by any of the ancestor windows, and should be 

forwarded further if meaningful. 

stsRequestDenied The key event was not processed by any of the ancestor windows, and was aborted 
at some level of the walk. No further processing should occur. 

stsOK The key event was processed. No further processing should occur. 

See Also msgWinSend 
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msgGWinForwardedKey 

Message received when a keyboard event is forwarded to a gWin. 

Takes P_INPUT_EVENT, returns STATUS. 

#define msgGWinForwardedKey MakeMsg(clsGWin, 18) 

Comments msgGWinForwardedKey is sent to a gWin when a keyboard event has been forwarded from a child 

window. Subclasses wishing to handle keyboard events forwarded from child windows should handle 
this message. 

gWin's default response is to return stsRequestForward. 

Do not send this message; it should only be self sent by clsGWin. 

Return Value stsRequestForward The key event was not processed and should be forwarded further. 

stsRequestDenied The key event was not processed and should not be forwarded any further. 

stsOK The key event was processed and should not be forwarded any further. 



msgGWinBadKey 

Self sent to allow a subclass to handle bad keys. 

Takes P_INPUT_EVENT, returns STATUS. 

#define msgGWinBadKey MakeMsg (clsGWin, 23) 

Comments gWin's default response is to return stsOK. 

gWin self sends msgGWinBadKey when (1) msgGWinKey returns stsRequestDenied, (2) 
msgGWinKey returns stsRequestForward and style.keyboardForward is not set, or (3) 
msgGWinForwardKey returns stsRequestDenied or stsRequestForward. 

msgGWinlsComplete 

Called to determine if a gesture was sent while processing input. 

Takes P_GWIN_GESTURE, returns STATUS. 

#define msgGWinlsComplete MakeMsg (clsGWin, 24) 

Message typedef struct GWIN_GESTURE { 

Arguments MESSAGE msg; // gesture Id 

RECT32 bounds; // bounding box in LWC 

XY32 hotPoint; // gesture hot point 

OBJECT uid; // object in which the gesture was generated 

U32 reserved; // reserved for future use 
} GWIN_GESTURE, *P_GWIN_GESTURE; 

Comments This message is used to determine if the gesture may have been sent other than when processing 

msgGWinXList or msgQuickHelpHelpShow. Put simply, this message returns stsOK for any gesture 
other then those sent while processing input where gesture processing may continue. Examples are 
press-hold and tap-press hold. 

Return Value stsRequestDenied The gesture was sent while processing input The gesture was sent 

from msgGWinXList ormsgQuickHelpHelpShow. 



GWIN.H 651 

Messages from Other Classes 



msgGWinGestureDone 

Sent to indicate the end of a gesture. 

Takes P_GWIN_GESTURE, returns STATUS. Category: self-sent. 

♦define msgGWinGestureDone MakeMsg(clsGWin, 25) 

message typedef struct GWIN_GESTURE { 

Arguments MESSAGE msg; // gesture Id 

RECT32 bounds; // bounding box in LWC 

XY32 hotPoint; // gesture hot point 

OBJECT uid; // object in which the gesture was generated 

U32 reserved; // reserved for future use 
} GWIN_GESTURE, *P_GWIN_GESTURE; 

Comments As part of its default response to msgGWinXList, gWin self sends msgGWinGestureDone. 

(msgGWinXList is self sent after the forwarding protocol has completed but before 

msgQuickHelpShow or msgGWinBadGesture is sent.) g 

z 
It is intended for use by classes that modify their state in anticipation of receiving msgGWinGesture 

and fail to receive it. (For instance, a subclass could handle msgGWinGesture and not pass the message 

along to its ancestor). Such classes should watch for msgGWinAbort and msgGWinGestureDone. 

Either, but not both, could be sent for any one gesture. 

Subclasses may field msgGWinGestureDone but must also allow their ancestor to see the message. 

Messages from Other Classes 

msgFree 

Defined in clsmgr.h. 

Takes OBJJCEY, returns STATUS. 

Comments In response to msgFree, gWin removes itself as an observer of its translator and then destroys the 

translator. In addition, gWin frees any memory it has allocated. 

msgSave 

Defined in clsmgr.h. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments In response to msgSave, gWin saves state information. gWin files its helpld if the helpld is different 

then the window tag. 

Note that the gWin s translator is not saved or restored since the translator only exists while the gWin is 
actively collecting strokes. 

msgRestore 

Defined in clsmgr.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments In response to msgRestore, gWin restores state information, including the helpld. 

Note that the gWin's translator is not saved or restored since the translator only exists while the gWin is 
actively collecting strokes. 
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msgWinSend 

Defined in win.h. 

Takes P_WIN_SEND, returns STATUS. 

:©mments gWin handles msgWinSend if pArgs->msg is msgGWinForwardedGesture or 

msgGWinForwardedKey. For all other values of pArgs->msg, gWin simply passes the message to its 
ancestor. 

If pArgs->msg is msgGWinForwardedGesture, gWin self sends msgGWinForwardedGesture. If this 
returns stsRequestForward and the gWin s style.gestureForward is set, gWin passes the msgWinSend to 
its ancestor, allowing the forwarding to continue. Otherwise gWin returns the result of the self send of 
msgGWinForwardedGesture. 

If pArgs->msg is msgGWinForwardedKey, gWin self sends msgGWinForwardedKey. The response to 
this message is handled similarly to the gesture case, except that style.keyboardForward is checked rather 
than style.gestureForward. 

lee Also msgGWinForwardKey 

msglnputEvent 

Defined in input.h. 

Takes P_INPUT_EVENT, returns STATUS. 

:omments This is the main processing message for gWin. 

For keyboard events, gWin self sends msgGwinKey, and performs the keyboard processing and 
forwarding as described earlier. 

For pen events, gWin returns stsInputTerminate if gestureEnable is not set. Otherwise, gWin initiates a 
grab by returning stsInputGrabTerminate on msgPenDown if style.grabDown is set. 

On msgPenStroke events gWin self sends msgGWinStroke and continues the grab by returning 
stsInputGrabTerminate. 

On msgPenOutProxUp, msgPenOutProxDown, or msgPenTimeout gWin self sends 
msgGWinComplete and releases the grab by returning stsInputTerminate. 

For other pen events, gWin returns stsInputTerminate or stsInputTerminate if it "grabbing" (has 
returned stsInputGrabTerminate due to a msgPenDown or msgPenStroke), and not 
" released- the-grab" (returned stsInputTerminate due to a msgPenOutProxDown, msgPenOutProxUp, 
or msgPenTimeout). 

If gWin receives a msgPenTap, is not "grabbing", and has gestureEnable set, gWin synthesizes a tap 
gesture by self sending msgGWinXList. Thus, even though if inputStroke events are turned off in the 
window, gWin can still recognize tap gestures. 

letym Value stsInputGrabTerminate Temporarily grabbing input events Not grabbing input events. 

See Also msgGWinStroke 
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msgQuickHelpHelpShow 

Defined in qhelp.h. 

Takes P_XY32, returns STATUS. 

Comments The theQuickHelpManager sends msgQuickHelpHelpShow to a gWin to ask the gWin to display the 

gWin's quick help. (This is the message that theQuickHelpManager sends when the user taps while in 
quick help mode.) 

gWin's default response is to self send msgGWinGesture; the gesture sent along with this 
msgGWinGesture is a synthesized help gesture. 

If the response to the msgGWinGesture is stsRequestForward, gWin self sends 

msgGWinForwardGesture. If the response to the msgGWinForwardGesture is stsRequestForward, 

gWin self sends msgQuickHelpShow to theQuickHelpManager with a helpld of 

hlpQuickHelpNoHelp. (In response to this, theQuickHelpManager displays the "no help available" 

text to the user.) 2 

msgXlateCompleted 

Defined in xlate.h. 

Takes nothing, returns STATUS. 

Comments A gWin's gesture translator sends msgXlateCompleted to the gWin when a gesture translation is 

complete. (The gWin has previously started the translation by sending msgScrComplete to the gesture 
translator.) 

gWin's default response is to extract the xlist from the translator and self send msgGWinXList. 

See Also msgGWinXList 
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HWCUSTOM.H 



This file contains definitions for clsHWCustomFrame. 

clsHWCustomFrame inherits from clsFrame. 

This file contains the API definition for clsHWCustomFrame. Instances of clsHWCustomFrame are 
created by the Settings Notebook when the user taps the "Customize" button on the Installed 
Handwriting page. The Settings Notebook will pass in the handle of the prototype set to be customized. 
It is up to clsHWCustomFrame instances to carry out the customization and destroy themselves when 
finished. 



Debugging Flags 

clsHWCustomFrame uses the Handwriting debug flag set 'Z'. clsHWCustomFrame uses: 
40000 Show all internal debugging messages 



#ifndef HWCUSTOM_INCLUDED 
#define HWCUSTOM_INCLUDED 
tifndef FRAME_INCLUDED 
tinclude <frame.h> 
#endif 

#ifndef FS_INCLUDED 
♦include <fs.h> 
tendif 



Common #defines and typedefs 



typedef struct HWCUSTOM_NEW_ONLY { 

OBJECT protoSetHandle; // handle of prototype set to customize 
} HWCUSTOM_NEW_ONLY; 

tdefine hwCustomNewFields \ 
frameNewFields \ 
HWCUSTOM_NEW_ONLY hwcustom; 

typedef struct HWCUSTOM_NEW { 

hwCustomNewFields 
} HWCUSTOM_NEW, *P_HWCUSTOM_NEW; 

File System Attributes 

The values for the 32-bit attribute hwCustomAttrCustomizable are: 

0: This profile is fully customizable. 

1 : This engine allows customization, but this profile is the original, generic profile for this engine; users 
must rename it before they customize it. This will to prevent users from inadvertently overwriting the 
original copy of the profile on the distribution media. If the attribute is 1, Handwriting Customization 
will pop up a dialog forcing the user to copy or rename the profile before customization. 

2: This profile is not customizable. 

Any other value: Same as 0; profile is fully customizable. 
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If the attribute is missing from the directory, Customization will assume the profile is fully customizable. 
Here is the magic incantation to stamp the attribute on a profile: 

STAMP /G "<profile>" /A 800278 <value> 
For instance, the GO Write profile gets stamped like this: 

STAMP /G "GOWrite" /A 800278 1 
This will stamp a value of 1 on the GOWrite directory for Admin 316 (clsHWCustomFrame), Index 1. 
#define hwCustomAttrCustomizable FSMakeFix32Attr (clsHWCustomFrame, 1) 



Messages 



msgNewDefaults 

Initializes the HWCUSTOM_NEW structure to default values. Default values are the same as for clsFrame, 
with a protoSetHandle of 0. 

Takes P_HWCUSTOM_NEW, returns STATUS. Category: class message. 



typedef struct HWCUSTOM_NEW { 

hwCustomNewFields 
} HWCUSTOM NEW, *P HWCUSTOM NEW; 



msgNew 

Creates a handwriting customization frame window, acting on the handwriting prototype set in 
pArgs->hwcustom.protoSetHandle. If protoSetHandle==0, acts on theCurrentlnstalledHWXProtos. 

Takes P_Hw~CUSTOM_NEW, returns STATUS. Category: class message. 



typedef struct HWCUSTOM_NEW { 

hwCustomNewFields 
} HWCUSTOM NEW, *P HWCUSTOM NEW; 



Quick Help Tags 



#define hlpHWCustomlcon 
#define hlpHWCustomNote 
#define hlpHWCustomAlert 
#define hlpHWCustomExitNote 
tdefine hlpHomeWinLCLabel 
tdefine hlpHomeWinUCLabel 
tdefine hlpHomeWinNumLabel 
tdefine hlpHomeWinSymLabel 
tdefine hlpHomeWinSCLabel 
tdefine hlpHomeWinExitLabel 
#define hlpHomeWinNextArrow 
#define hlpHomeWinStatTitle 
tdefine hlpHomeWinStatTSets 
tdefine hlpHomeWinStatRecRt 
tdefine hlpHomeWinStatLeam 
tdefine hlpHomeWinStatRecom 
tdefine hlpHomeWinlnstrs 
tdefine hlpHomeWinBlankAreas 
tdefine hlp26WinTitle 
tdefine hlp26WinLearnBtn 
tdefine hlp26WinClearBtn 
tdefine hlp26WinNextBtn 
tdefine hlp26WinDoneBtn 
tdefine hlp26WinInstrs 
tdefine hlp26WinInputLabel 
tdefine hlp26WinInputBox 
tdefine hlp2 6WinBlankAreas 



MakeTag (clsHWCustomFrame, 0) 
MakeTag (clsHWCustomFrame, 1) 
MakeTag (clsHWCustomFrame, 2) 
MakeTag (clsHWCustomFrame, 25) 
MakeTag (clsHWCustomFrame, 5) 
MakeTag (clsHWCustomFrame, 6) 
MakeTag (clsHWCustomFrame, 7) 
MakeTag (clsHWCustomFrame, 8) 
MakeTag (clsHWCustomFrame, 9) 
MakeTag (clsHWCustomFrame, 10) 
MakeTag (clsHWCustomFrame, 4) 
MakeTag (clsHWCustomFrame, 21) 
MakeTag (clsHWCustomFrame, 22) 
MakeTag (clsHWCustomFrame, 23) 
MakeTag (clsHWCustomFrame, 24) 
MakeTag (clsHWCustomFrame, 26) 
MakeTag (clsHWCustomFrame, 11) 
MakeTag (clsHWCustomFrame, 3) 
MakeTag (clsHWCustomFrame, 12) 
MakeTag (clsHWCustomFrame, 13) 
MakeTag (clsHWCustomFrame, 14) 
MakeTag (clsHWCustomFrame, 15) 
MakeTag (clsHWCustomFrame, 16) 
MakeTag (clsHWCustomFrame, 18) 
MakeTag (clsHWCustomFrame, 19) 
MakeTag (clsHWCustomFrame, 20) 
MakeTag (clsHWCustomFrame, 17) 
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HWLETTER.H 



This file contains definitions for clsHWLetterFrame. 

clsHWLetterFrame inherits from clsFrame. 

This file contains the API definition for clsHWLetterFrame. Instances of clsHWLetterFrame are 
created by the Settings Notebook when the user taps the "Practice" button on the Installed Handwriting 
page. The Settings Notebook will pass in the handle of the prototype set to practice. It is up to 
clsHWLetterFrame instances to carry out the practice session and destroy themselves when finished. 

Debugging Flags 

clsHWLetterFrame uses the Handwriting debug flag set 'Z\ clsHWLetterFrame uses: 
1 0000 Show all internal debugging messages 

#ifndef HWLETTER_INCLUDED 
#define HWLETTER_INCLUDED 

#ifndef FRAME_INCLUDED 
♦include <frame.h> 
#endif 



Common #defines and typedefs 



typedef struct HWLETTER_NEW_ONLY { 

OBJECT protoSetHandle; // handle of prototype set to practice 
} HWLETTER_NEW_ONLY; 

tdefine hwLetterNewFields \ 
frameNewFields \ 
HWLETTER_NEW_ONLY hwletter; 

typedef struct HWLETTER_NEW { 

hwLetterNewFields 
} HWLETTER NEW, *P HWLETTER NEW; 



Messages 



msgNewDefaults 

Initializes the HWLETTER_NEW structure to default values. Default values are the same as for clsFrame, 
with a protoSetHandle of 0. 

Takes P_HWLETTER_NEW, returns STATUS. Category: class message. 

Message typedef Struct HWLETTER_NEW { 

Arguments hwLetterNewFields 

} HWLETTER NEW, *P HWLETTER NEW; 
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msgNew 

Creates a handwriting practice frame window, using the handwriting prototype set in 
pArgs->hwletter.protoSetHandle. If protoSetHandle==0, uses the current InstalledHWXProtos. 

Takes P_HWLETTER_NEW, returns STATUS. Category: class message. 



typedef Struct HWLETTER_NEW { 

hwLetterNewFields 
} HWLETTER NEW, *P HWLETTER NEW; 



Quick Help Tags 



#define hlpLetterPractice 
#define hlpLWInputSPaper 
tdefine hlpLWKeyboard 
#define hlpLWPrevScribble 
#define hlpLWXlateResult 
#define hlpLWAnimationWin 



MakeTag(clsHWLetterFrame, 1) 

MakeTag(clsHWLetterFrame, 2) 

MakeTag(clsHWLetterFrame, 3) 

MakeTag(clsHWLetterFrame, 4) 

MakeTag(clsHWLetterFrame, 5) 

MakeTag(clsHWLetterFrame, 6) 



PENPOINT API REFERENCE / VOL I 
PART 5 / INPUT AND HANDWRITING 



INPUT.H 



This file contains the API definition for clslnput and PenPoint's input system. 
clslnput inherits from clsObject. 

clslnput provides the object-oriented interface to PenPoint's input system. 
The functions described in this file are contained in INPUT.LIB. 

Introduction 

PenPoint's input system collects events generated by devices such as thePen and theKeyboard. It then 

distributes those events to other objects in the system. 

The input system is almost always single-threaded. Usually only one input event is being distributed 

through the system at any given time. The exception is when using msglnputModalStart and 

msglnputModalEnd. 



Road Map 



This file contains general information about PenPoint's input system and input events. Information 
specific to pen events is in pen.h. Information specific to key events is in key.h. 
Most PenPoint application programs do not need to use the PenPoint input system directly. PenPoint 
has several classes that manage input for clients. Check these classes to see if they meet your needs. 
Candidate classes include the following (and their subclasses). (This list is not exhaustive.) 

clsGWin (gwin.h) 

clsSPaper (spaper.h) 

clsIP (insert.h) 

clsNotePaper (notepapr.h) 

all toolkit classes. 

Any client handling input directly (rather than using PenPoint classes which handle input) needs to 
understand the following: 

♦ How to set up window input flags so that desired input events are received. See the section "Input 
Flags." 

♦ How to handle msglnputEvent in general, and how to handle the device-specific values for 
msglnputEvent's pArgs->devCode. See pen.h and key.h. 

♦ How to return appropriate status values in response to msglnputEvent. See "Return Values From 
msglnputEvent." 

Any client that needs to grab input needs to understand: 

♦ General grabbing information. See the section "Grabs and Grabbers." 
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♦ msglnputEvent return values that start a grab and keep a grab going. See "Return Values From 
msglnputEvent. " 

Any client that needs to be the input target (and therefore the recipient of keyboard events) needs to 
understand: 

♦ InputSetTargetO 

The other interfaces described in this file are typically used by sophisticated clients. 



Overview 

This diagram illustrates the flow of events into, through and out of the input system: 
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I Pen | 
+ + + 
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I Keyboard | 
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I Pre-specified | | XY | | Target | 

I Destination | | | | | 

+ + + + + + 



+ + 

Each of these major pieces is described below: 

♦ Devices such as the pen and keyboard generate low-level input events. (These "devices" are partially 
implemented in the MIL and partially implemented in PenPoint.) These low-level input events are 
converted into PenPoint input events and are sent to the Input Queue. 

♦ The input system pulls events off the queue one at a time and decides where to send or "route" the 
event. 

There the "event routing" process starts. 

♦ First the event is run through the list of Filters. Filters have the opportunity to examine each input 
event. Filters are ordered by their priority. Filters return a status which indicates how processing of 
the event should continue. 

♦ Next the event is sent to the current grab object, or grabber. (There might not be a current grabber, 
in which case this step is skipped.) The grabber returns a status which indicates how processing of 



y Filters 
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the event should continue and whether the grab should continue. The input system maintains a 
stack of grabbers to support nested modal behavior. 

The next step in an event's routing depends in part on the event. (Only one of these alternatives is used.) 

♦ If the event has a pre-specified destination, msglnputEvent is sent to that destination. If the event 
has a pre-specified destination, it is found in pArgs->listener for msglnputEvent. An event has a 
pre-specified destination only if the event has been programmatically inserted into the input system. 

♦ If the event has a "valid" XY coordinate (which typically means it was generated by thePen), the 
event is routed to window objects. The top-most window (farthest from theRootWindow) which 
encloses the XY coordinate gets the first opportunity to process the event. Each window may 
terminate processing of the event or allow the input system to send the event to its (the window's) 
parent window. 

♦ Otherwise the event is sent to the current input target, if the target is non-null. (This is how all 
keyboard events are routed.) 



Filters are used to implement some types of modal behavior. Typically this modal behavior is relatively 
long-lived. For instance, PenPoint's Quick Help mode is implemented using filters. 

It is extremely rare for PenPoint application programs to directly use or even be aware of filters. 

Object Priority 



qhelp win 


16 




vkey win 


32 




qhelp nb 


32 




vkey app 


80 




spell (proof) 


96 




insertion pad 


96 ( 


if modal ) 


menu 


112 




note 


160 




option 


160 





Grabs and Grabbers 

Grabbers are used to implement light-weight modal behavior. These modes are typically pen controlled 
in that they start and end with some pen event, such as msgPenDown and msgOutProxUp. For 
instance resize handles are implemented using grabbers. 

Many application programs never use grabbers directly but rather use PenPoint classes that use grabbers. 

As illustrated in the "Overview" section, the current grabber gets input messages after filters but before 
"normal" event distribution occurs. The grabber can "swallow" the event and stop any further 
distribution, or the grabber can allow distribution to continue. 

There are two ways to start a grab. 

♦ An object that is handling msglnputEvent can return a status value that tells the input system that it 
wants to be the grab object. See the section "Return Values from msglnputEvent." 

♦ Any object can call InputSetGrab() passing in the object to become the grabber. 

A grabber terminates a grab by returning from msglnputEvent a status value that does not have "Grab" 
turned on, or by setting the current grabber to objNull. 



662 PENPOINT API REFERENCE 

Part 5 / Input and Handwriting 

In order to keep the grab "alive," the grabber must always return a status from msglnputEvent that 
implies "Grab." If the input system gets a status returned that does not have "Grab" implied, it 
terminates the grab. 

#ifndef INPUT_INCLUDED 
#define INPUT_INCLUDED 
tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 

tifndef UID_INCLUDED 
tinclude <uid.h> 
#endif 

#ifndef GEO_INCLUDED 
#include <geo.h> 
#endif 

#ifndef CLSMGR_INCLUDED 
#include <clsmgr.h> 
#endif 

Common #defines and typedefs 

Miscellaneous 

The following flags control event distribution to filters. 

iflSendMyWindowOnly tells the input system to not bother sending the message to the filter unless the 
event happened in the filter or in one of the filter s window children or window ancestors. It is strictly a 
performance enhancement. 

typedef U32 FILTER_FLAGS, *P_FILTER_FLAGS; 

#define iflWindow flagO // Private. Internal use only. 

#define iflSendMyWindowOnly flagl 

This is the number of bytes in the INPUT_EVENT's eventData field. The data stored in this field depends 
on the devCode field. Handlers of msglnputEvent never need to use this value; all handlers will cast 
pArgs->eventData to an appropriate type. 

#define inptEDataSize 32 // no of bytes INPUT_EVENT' s eventData field 

Return Values From msglnputEvent 

Overview 

The status returned from msglnputEvent tells the input system how to continue processing the event. 
This section lists the STATUS values that recipients of msglnputEvent may return. Each of these statuses 
contains several "values." (Not all possible combinations of these are legal or supported.) 

♦ Whether distribution for the event should continue or be terminated. 

♦ Grab status. Whether to start or continue a grab for the recipient of msglnputEvent. 

♦ Ancestor interest. Whether or not the ancestor class was interested in the event. 

♦ Filter skip. For filters only, whether distribution of the event should skip certain filters. 

The following table describes the relationship between the legal status codes and the values they 
"contain." For clarity, the "no" entries are left blank and the "Filter skip" information is not shown. 
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Return Values From msglnputEvent 



Pf^ Details 



start 

continue or ignored 

distri- continue by 

bution grab ancestor 



stsInputContinue 


yes 






st s Input Terminate 








stsInputGrabContinue 


yes 


yes 




stsInputGrabTerminate 




yes 




st s Input Grab 




yes 




sts Input Ignored 


yes 




yes 


stsInputGrablgnored 


yes 


yes 


yes 



These status values can be returned by any handler of msglnputEvent: 

stsInputContinue Distribution of this event should continue. 

stsInputTerminate Distribution of this event should terminate. 

StsInputGrabContinue Distribution of this event should continue, and the grab should be continued 
(or started) for the recipient of msglnputEvent. 

stsInputGrabTerminate Distribution of this event should terminate, and the grab should be continued 
(or started) for the recipient of msglnputEvent. 

stsInputGrab Same as stsInputGrabTerminate. 

stslnputlgnored An ancestor class may return stslnputlgnored to inform a subclass that the ancestor 
was not interested in the event. The input system treats stslnputlgnored just like stsInputContinue. 

stsInputGrablgnored An ancestor class may return stsInputGrablgnored to inform a subclass that the 
ancestor was not interested in the event, but that the grab should be continued (or started) for the 
object the received msglnputEvent. The input system treats stsInputGrablgnored just like 
stsInputGrabContinue. 

These statuses should only be returned by Filters: 

stsInputSkip Distribution of this event should continue but all remaining filters should be skipped. 

stsInputSkipTo2 Distribution of this event should continue but all remaining filters in Range 1 
(priority less than 64) should be skipped. 

stsInputSkipTo3 Distribution of this event should continue but all remaining filters in Ranges 1 and 2 
(priority less than 128) should be skipped. 

stsInputSkipTo4 Distribution of this event should continue but all remaining filters in Ranges 1 , 2 
and 3 (priority less than 192) should be skipped. 

stsInputTerminateRemoveStroke Distribution of this event should terminate, and any other events 
corresponding to the current stroke should not be sent at all. 

stsInputGrabTerminateRemoveStroke Distribution of this event should terminate, the grab should be 
continued (or started) for the recipient of msglnputEvent, and any other events corresponding to 
the current stroke should not be sent at all. 

♦define stsInputContinue InputMakeSts(O) 

♦define stsInputSkip InputMakeSts (evSkip) 

♦define sts Input SkipTo2 InputMakeSts (evSkip | (1 « 4)) 

♦define stsInputSkipTo3 InputMakeSts (evSkip | (2 « 4)) 

♦define stsInputSkipTo4 InputMakeSts (evSkip | (3 « 4)) 

♦define stsInputTerminate InputMakeSts (evTerminate) 
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♦define stsInputGrabContinue InputMakeSts (evGrab) 

♦define stsInputGrabTerminate InputMakeSts (evGrab | evTerminate) 
♦define stsInputGrab InputMakeSts (evGrab | evTerminate) 

♦define stsInputTerminateRemoveStroke InputMakeSts (evTerminate | evStroke) 
♦define stsInputGrabTerminateRemoveStroke \ 

InputMakeSts (evGrab | evTerminate | evStroke) 
♦define stslnputlgnored InputMakeSts (evlgnore) 

♦define stsInputGrablgnored InputMakeSts (evGrab | evlgnore) 



Other Statuses 

♦define stsInputQueueFull 



MakeStatus(clsInput, evOther | 2) 



Input Flags 

Overview 

Each window has a set of input flags that are stored in the windows win.flags.input field. These flags can 
be manipulated while handling msgNew and msgNewDefaults. They can also be manipulated with 
several other window messages; see win.h for more information. 

InputSetGrab() and InputFilterAdd use these flags as one of their parameters, 
typedef U32 INPUT_FLAGS, *P_INPUT_FLAGS; 

"Interest" Flags 

PenPoint s input system can generate many messages. Most clients are only interested in a subset of the 
messages that can be generated. So clients can provide hints to the input system about the input events 
the client is interested in. This reduces the message traffic and increases performance. For instance, if a 
client is not interested in pen movement events when the pen is up above the writing surface (but within 
proximity), the client can clear the inputMoveUp flag 

Typically, a flag enables or disables several input events. For instance, setting the inputTip flag enables 
both msgPenDown and msgPenUp (see pen.h). 

You should treat these flags as a hint to the input system. You should not assume that a specific input 
event will not arrive because you have not enabled the corresponding bit in the input flags. 

This table contains examples of the messages that are enabled by setting various flags. This table is only 
representative — it is not complete! 





example of 


message defined 


input flag 


message (s) enabled 


in 


inputTip 


msgPenUp, msgPenDown 


pen.h 


inputMoveUp 


msgPenMoveUp 


pen . h 


input Mo veD own 


msgPenMoveDown 


pen.h 


inputEnter 


msgPenEnterUp, msgPenEnterDown 


pen.h 


inputExit 


msgPenExitUp, msgPenExitDown 


pen.h 


input InProx 


msgPenlnProxUp 


pen.h 


inputOutProx 


msgPenOutProxUp 


pen . h 


inputStroke 


msgPenStroke 


pen.h 


inputTap 


msgPenTap 


pen.h 


inputHoldTimeout 


msgPenHoldTimeout 


pen.h 


inputChar 


msgKeyChar 


key.h 


inputMultiChar 


msgKeyMulti 


key . h 


inputMakeBreak 


msgKeyUp, msgKeyDown 


key.h 
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♦define inputTip 
♦define inputMoveUp 
♦define inputMoveDown 
♦define inputEnter 
♦define inputExit 
♦define inputlnProx 
♦define inputOutProx 
♦define inputStroke 
♦define inputTap 
♦define inputChar 
♦define inputMultiChar 
♦define inputMakeBreak 
♦define inputHoldTimeout 



♦define inputTimeout 
♦define inputHWTimeout 
♦define inputMoveDelta 



♦define inputDestOnly 
♦define inputLRContinue 
♦define inputDi sable 
♦define inputEnableAll 



(U32) (flagO) 
(U32) (flagl) 
(U32) (flag7) 
(U32) (flag2) 
(U32) (flag3) 
(U32) (flag4) 
(U32) (flag5) 
(U32) (flag6) 
(U32) (flaglO) 
(U32) (flagl3) 
(U32) (flagl4) 
(U32) (flagl5) 
(U32) (flag8) 

(U32) (flag9) 
(U32) (flagll) 
(U32) (flag!8) 



(U32) (flagl9) 
(U32) (flag20) 
(U32) (flag21) 
(U32) (flag25) 



// enable TipUp & TipDown events 

// enable MoveUp events 

// enable MoveDown events 

// enable EnterUp & EnterDown 

// enable ExitUp & ExitDown 

// enable InProxUp events 

// enable OutProxUp events 

// enable Stroke events (See pen.h.) 

// enable tap events 

// enable character events 

// enable multi-char events 

// enable make /break events 

// enable HoldTimeout events (See 

// "Hold Timeout Events" in pen.h) 

// obsolete. 

// obsolete. 

// enable compression of multiple 

// delta events into a single delta 

// event. Good news: fewer messages 

// and better performance. Bad news: 

// less information to the client. 

// send event iff destination is self 

// enable dist. to parent windows 

// send no input event messages 

// enables all events to be sent to 

// grabbers 



Inking Flags 



WARNING: Inking and the acetate are subject to major changes in future releases. 

♦define inputlnk (U32) (flag23) 
♦define input InkThrough (U32) (flag24) 

♦define inputlnkDisable (U32) (flag30) 



// enable inking in the acetate layer 

// enable inking in window rather 

// than acetate layer 

// disables both inputlnk and 

// input InkThrough 



Miscellaneous Flags 

inputNoBusy If cleared, then the input system automatically turns on PenPoint's busy clock if the 
recipient of a message does not return before a certain timeout. If set, this default busy clock 
behavior is disabled. 

inputResolution If set, msgPenMoveUp and msgPenMoveDown messages are sent each time the pen 
moves one digitizer unit. (In other words, the input system sends a move event for even the smallest 
detectable amount of movement. If cleared, move events are sent only when the pen has moved at 
least one display pixel's size. 

inputAutoTerm Should only be set by a grabber. Specifies that all events that the grabber is not 
interested in should be treated as if the grabber returned stsInputGrabTerminate. 

inputGrabTracker Should only be set by a grabber. Specifies that the grabber does not need the input 
system to perform its normal hit detection. This is strictly a performance enhancement. (The name 
of this value is an anachronism. Originally trackers were the only grabbers that didn't need hit 
detection.) 



♦define inputNoBusy (U32) (flagl2) 
♦define inputResolution (U32) (flag22) 
♦define inputAutoTerm (U32) (flag26) 



♦define inputGrabTracker (U32) (flag27) 
♦define inputTransparent (U32) (flag31) 



// disable default busy clock 

// report pen resolution move events 

// automatically terminate all 

// events' distribution if grabber 

// doesn't have the event 

// flag enabled. 

// disables hit detect during grab 

// invisible to hit detect operations 

// See win.h. 
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#define inputSigVerify (U32) (flagl6) // Sets pen sample rate to high and 

// MIL reporting threshold to 0. 
// This does not guarantee getting 
// every pen move event, so users 
// should check timestamps to see 
// if any data has been lost. 

// Shorthand for all flags which correspond to real input events. 
#define inputAHRealEventsFlags (U32)0xEFFF 



Event Distribution Flags 



Input distribution flags give some additional information to thebeing sent the input event. 

evflFilter object is getting this event because it is a filter; 

evfGrab object is getting this event because it is a grabber; 

evfListener object is getting because it was specified in the input event listener field; 

evfTarget object is getting this event because it is the target; 

evfXYLeafToRoot object is getting this event as part of the XY distribution; 

evflnSelf event occurred in this window; 

evflnChild event occurred in a child of this window; 

NOTE: evflnSelf and evflnChild will become obsolete in future releases. 

evfGrabTracker object had input grab tracker flag on. 

typedef U32 INPUT_DIST_FLAGS, P_INPUT__DIST_FLAGS; 

// NOTE: evflnSelf and evflnChild will become obsolete in future releases. 
#define evflnParent ((U32)flag9) // Obsolete. 



#define evflnChild ( (U32) flaglO) 

#define evflnSelf ( (U32)flagll) 

#define evfGrabTracker ( (U32) flagl2) 

#define evfFilter ( (U32) flag26) 

#define evfGrab ( (U32)flag27) 

#define evfXYLeafToRoot ( (U32)flag29) 

#define evfListener ( (U32)flag30) 



#define evfTarget 



((U32)flag31) 



// event occurred in child window 
// event occurred in this window 
// event occurred during grab 
// event in filter distribution 
// event in grab distribution 

// event in XY dist 
// event in "pre- specified 
// destination" distribution 
// event in target distribution 



Messages 



krauments 



msglnputEvent 

thelnputManager uses this message to deliver input events. 
Takes P_INPUT_EVENT, returns STATUS. 
typedef struct INPUT EVENT { 



SIZEOF 

INPUT_DIST_FLAGS 

MESSAGE 

OS_MILLISECONDS 

XY32 

OBJECT 



OBJECT 
OBJECT 
U8 
} INPUT_EVENT, *P_INPUT_EVENT; 

Idefine msglnputEvent 



length; // actual length of pArgs 

flags; // distribution information 

devCode; // input event 

timestamp; // time event was queued 

xy; // location of event 

listener; // pre-specified destination 

// Normally objNull. 
destination; 

originator; // originating device 

eventData[inptEDataSize] ; // event specific data 



MakeMsg( els Input, 0) 
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Comments pArgs->devCode contains the "event" that is being delivered. These events are device-specific. See pen.h 

for a list of pen events and key.h for a list of key events. 

The pArgs for msglnputEvent is best thought of as a union type. pArgs can always be cast to a 
P_INPUT_EVENT, but the content of pArgs->eventData depends on the value of pArgs->devCode. For 
some values of pArgs->devCode, the pArgs are actually larger than an INPUT_EVENT structure, so use 
the pArgs->length field to determine the length of the input event. For example, the msgPenStroke and 
msgKeyMulti events both have data which extends past the end of the INPUT_EVENT structure. 

For events that have a valid XY, pArgs->destination is the top-most window with input enabled 
(FlagOff(inputDisable, ...)). 

The recipient of this message must return one of the status values described in the section "Return 
Values from msglnputEvent." 

Notification Messages 



msglnputGrabPushed 

Notifies a grabbing object that it is being pushed onto the grabber stack and the pArgs is the new 
grabber. 

Takes OBJECT, returns STATUS. 

tdefine msglnputGrabPushed MsgNoError(MakeMsg(clsInput, 0x83)) 

msglnputGrabPopped 

Notifies a grabbing object that is being popped from the grabber stack and becoming the current 
grabber. 

Takes OBJECT, returns STATUS. 

tdefine msglnputGrabPopped MsgNoError (MakeMsg ( els Input, 0x84)) 

msglnputTargetDeactivated 

Notifies the input target that some other object is become the input target. 

Takes OBJECT, returns STATUS. 

#define msglnputTargetDeactivated MsgNoError (MakeMsg (clslnput, 0x85)) 



msglnputTargetActivated 

Notifies an object that it is becoming the input target. 

Takes OBJECT, returns STATUS. 

#define msglnputTargetActivated MsgNoError (MakeMsg (clslnput, 0x86)) 



Functions 



InputFilterAdd 

Adds a filter to the filter list. 
Returns STATUS. 
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Function Prototype STATUS EXPORTED InputFilterAdd( 
OBJECT newFilter, 

INPUT_FLAGS inputEventFlags, 

FILTER_FLAGS filterFlags, 

U8 priority 

>; 



InputFilterRemove 

Removes a filter from the filter list. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO InputFilterRemove ( 

OBJECT listener // filter to remove 

); 



InputEventlnsert 

Adds an event to the input event queue. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO InputEventlnsert ( 
P_INPUT_EVENT pEvent, 
BOOLEAN stamp 

); 

Comments Most clients do not use this message. 

If stamp is true, pEvent->timestamp is filled in with the current time and the event is added to the end 
of the queue. Otherwise, pEvent->timestamp is not modified and the event is placed at the head of the 
queue and the 

Itetom Value stsInputQueueFull the input system queue is full 



InputSetTarget 

Sets the input target object and flags. 

Returns STATUS. 

Function Prototype STATUS EXPORTED InputSetTarget ( 

OBJECT target, // new target object 

U32 flags // new target flags 

); 

Comments Clients use this message to set the input target. The input target is the object that receives 

msglnputEvent for all events that do not have an XY position ~ in particular, keyboard events. 

PenPoint's UI guidelines state that the selection owner and input target should usually be the same 
object. PenPoint does not enforce this association in any way. See the UI documentation and sel.h for 
more information. 

See Also msglnputTargetActivated.h 

InputGetTarget 

Returns the current input target. 
Returns OBJECT. 

Function Prototype OBJECT EXPORTED InputGetTarget (void) 

See Also InputSetTarget 
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InputSetGrab 

Sets the current grabber and its flags. 

Returns STATUS. 

Function Prototype STATUS EXPORTED InputSetGrab ( 

OBJECT grabber, // new grabber 

U32 flags // new grab input flags 

); 

Comments The previous grabber is pushed onto the grabber stack. 

If the flags parameter is 0, then inputAllRealEventsFlags is used. 

If both parameters are null, the current grabber is removed and the grabber on the top of the grabber 
stack (if the stack isn't empty) becomes the current grabber. 

InputGetGrab z 

Passes back the current grabber and its flags. 
Returns void. 

Function Prototype void EXPORTED InputGetGrab ( 

P_0BJECT pGrabber, // grabber 

P_U32 pFlags // current grab flags 
); 

See Also InputSetGrab 

msglnputModalStart 

Asks thelnputManager to start recursive input. 

Takes P_INPUT_MODAL_DATA, returns STATUS. 

Argymerrts typedef struct INPUT_MODAL_DATA { 

U32 reserved; 

U32 clientData[2]; 

} INPUT_MODAL_DATA, *P_INPUT_MODAL_DATA; 

#define msglnputModalStart MakeMsg( els Input, 1) 

Comments This message is used to implement a system-wide mode. Typical application programs should not sent 

this message. 

You must send this message to the input system using ObjectSendUpdate(). The sending task is blocked 
until the recursive task returns. The recursive task can pass data to the first task via pArgs. 

See Also msglnputModalEnd 

msglnputModalEnd 

Asks thelnputManager to terminate recursive input. 

Takes P_INPUT_MODAL_DATA, returns STATUS. 

fdefine msglnputModalEnd MakeMsg( els Input, 2) 

Message typedef Struct INPUT_MODAL_DATA { 

Arguments U32 reserved; 

U32 clientData[2]; 

} INPUT MODAL DATA, *P INPUT MODAL DATA; 
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merits This message terminates a system-wide mode. Typical application programs should not send this 

message. 

This message must be paired with msglnputModalStart. 

The sender of this message can pass information to the sender of msglnputModalStart by filling in 
pArgs. 

This message may be sent with ObjectCall() or ObjectSend(). 

Also msglnputModalStart 

msglnputActivityTimer 

Asks thelnputManager to enable or disable the activity timer. 

Takes BOOLEAN, returns STATUS. 

#define msglnputActivityTimer MakeMsg( els Input, 5) 

The input system maintains an "activity timer." Each time the input system has no events to process, 
the input system starts this timer. If no events are received before the timer expires, the input system 
puts PenPoint into Standby mode. This duration is typically several minutes long. 

Long running background tasks should first send msglnputActivityTimer with pArgs of false to tell 
thelnputManager to not turn off the machine. When the background operation is complete, the task 
should send the message again, but this time with a pArgs of true. 

thelnputManager keeps a nesting count which allows nested pairs of sends of this message. 



ummensfs 



INSERT.H 



This file contains the API definition for clsIP (Insertion Pads). 
clsIP inherits from clsCustomLayout. 

Introduction 

IPs provide a convenient and standard mechanism for getting handwritten input from a user. "IP" is an 
abbreviation for "Insertion Pad." 

IPs support several different visual styles -- character boxes, ruled lines, or blank writing areas and 
different optional behaviors. IPs use a translator to recognize handwriting if necessary. 

Typical Uses and Settings 

This section describes the most common uses and settings for the various types of IPs. 
Character Box IPs: 

♦ Their new.ip.style.displayType is ipsCharBox. 

♦ Character Box IPs are typically used to edit or insert simple strings of text such as a person's name or 
a document name. 

Ruled Line IPs: 

Their new.ip.style.displayType is ipsRuledLines. 

Ruled Line IPs are typically used when the handwriting preference is Ruled. 

When the preference is Ruled/Boxed, then the IP's style.ruledToBoxed and style. boxedToRuled 

fields are used to control the transmogrification between styles. It is the responsibility of the IP user 

to examine the preferences and determine if these fields should be set. 

Blank IPs: 

♦ Blank IPs are typically used to collect and display simple scribbles (perhaps a signature). 

♦ Their new.ip.style.displayType is ipsBlank. Their new.ip.style.buttonType is typically ipsNoButton, 
as they never do translation. 

♦ They do not display ruled lines in the sPaper created by default, nor do they allow scribble editing 
(see spaper.h). 

♦ They turn off borders when printing, allowing them to be robustly embedded inside a document. 



Quick Start 

A typical IP client does the following: 

♦ The client creates an IP in one of three styles described above. 

♦ The client then adds itself as an observer of the IP and handles msglPDataAvailable. 
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♦ The msglPDataAvailable handler uses msglPGetXlateString to extract the string and then 
processes the string in some application specific manner. 

The client should also handle either msglPCancelled or msgFreePending so that the client can free any 
allocated data when the IP is destroyed. 

IP Components 

An IP is constructed from several pieces. Most clients and subclasses don't need to know anything about 
these details, but advanced clients and subclasses might. 

The main writing area of an IP is either a field or an sPaper. An ipsCharBox IP contains a field (an 
instance of clsField); ipsRuledLines IP's contain sPaper, as do ipsBlank/ipsSignature. IP's which have 
style.ruledToBoxed or style.boxedToRuled set switch between a field and an sPaper. The IP is an 
observer of the sPaper or field. The sPaper or field has an associated translator. 

If style.buttonType is ipsBottomButtons or ipsTopButtons, then the IP also contains a command bar 
with three buttons. The IP is the client of all of the buttons in the command bar. 

Technically clients and subclasses can modify these components directly, but this is not recommended. If 
these components are modified directly, extreme care must be taken ~ current and future 
implementations of IP may make assumptions which can be violated by making some types of changes 
to the components. 

Client and Observers 

There are two different paths for objects to receive "notification" messages from an IP. 

If an IP's client is non-null, then the IP sends the following messages to the IP's client. If the client is 
null, then the IP sends the messages to the IP's observers. Self is the value of pArgs for all of these 
messages. 



♦ 


msglPCancelled 


♦ 


msglPClear 


♦ 


msglPDataAvailable 


♦ 


msglPCopied 


♦ 


msgl PTransmogrified 



IPs and Translators 

The sPaper or field component of an IP (whichever exists) has a translator which performs handwriting 
recognition. 

The creator of the IP may specify this translator in two ways: 

♦ A translator object may be passed to msgNew. Do this by setting new.ip.stylcxlateType to 
ipXlateObject and new.ip.xlate.translator to the translator object's uid. 

♦ An (optionally null) translation template may be passed to msgNew. Do this by setting 
new.ip.style.xlateType to ipXlateTemplate and new.ip.xlate.pTemplate to the address of the 
template. If the template is non-null, the IP compiles the template. Then the IP creates a translator 
(of clsXText; see xtext.h). This translator is created with the passed-in template if the template is 
non-null. 
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An IP with style. charOnly sets the translator to recognize single characters. 

The translation information (the translator object and the digested template) are destroyed when the IP 
handles msgFree. 

See msglPSetTranslator for additional information. 

IP Destruction 

As a convenience, an IP will optionally self destruct after providing its data or if the IP is cancelled. To 
get this behavior, set the IP's style.freeAfter to true. 

The automatic destruction occurs during an IP's default response to the following messages: 



msglPGetXlateData 

msglPGetXlateString 

msglPCancelled 



Transmogrification 

One of PenPoint's standard handwriting styles is called Ruled and Boxed. 

When writing in this style, the following steps are taken: (1) the user writes into a ruled line (sPaper) IP 
and hits OK. (2) the handwriting is translated. (3) the ruled writing area is replaced by a combed field. 
(4) the user makes any corrections in the field and presses OK again. (5) the data is made available to the 
application and (6) either the IP is destroyed or the combed field is replaced with a ruled line sPaper 
ready for additional input. 

The term 'Transmogrification" describes the switching of writing area types and the moving of the data 
from the ruled lines to the field. 

This transmogrification can happen in response to several messages, including msglPClear, 
msglPGetXlateData and msglPXlateCompleted. 

During transmogrification, the IP's style.displayType is changed. Also, the unnecessary components are 
destroyed and new ones created. The translator associated with the sPaper or field (whichever exists) is 
moved to the newly created sPaper or field (whichever didn't exist). 

The ruledToBoxed and boxedToRuled fields in an IP's style determine when transmogrification 
happens: 

ruledToBoxed 

♦ If style.ruledToBoxed is true, then a ipsRuledLines IP transmogrifies into a ipsCharBox IP when 
translation occurs. 

♦ Clients typically set style.ruledToBoxed to true if the prlnputPadStyle preference is 
RuledAndBoxed. 

boxedToRuled 

♦ If style.boxedToRuled is true, then a ipsCharBox IPs transmogrifies into a ipsRuledLines IP when 
data is retrieved via msglPGetXlateData or msglPGetXlateString. 

♦ Clients typically set style.boxedToRuled to true only if (1) the prlnputPadStyle preference is 
RuledAndBoxed and (2) the IP is to be used multiple times before it is freed. 
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IPs and Preferences 

This section describes the preferences that an IP considers and when it considers them. It also describes 
the preferences a client might consider when determining an IP's style. (See prefs.h for general 
information on preferences.) 

When handling msgNew, msglPSetStyle, and when transmogrifying, an IP uses the user's preferred 
value for Character Box Height, Character Box Width and Line Height. The IP does NOT observe 
these preferences so changes in their value won't affect an existing IP unless its style changes or the IP is 
transmogrified. 

Clients may want to consider the following preferences when managing an IP and its translator. (A 
client may want to only check the preference when creating the IP. Alternatively, a client may want to 
observe theSystemPreferences and respond to changes.) Note that this is only one possibility -- many 
clients will (correctly) chose to ignore the preferences or map from the preferences to IP characteristics 
differently. 

prlnputPadStyle: 

♦ If this is prlnputPadStyleRuledAndBoxed, the client would set an IP's style. displayType to 
ipsRuledLines and style.ruledToBoxed to true and possibly style.boxectroRuled to true. This causes 
an IP to transmogrify between ipsRuledLines and ipsCharBox display types. (See the section 
'Transmogrification" for details.) 

♦ If this is prlnputPadStyleRuled, the client would set an IP's style.displayType to ipsRuledLines and 
style.ruledToBoxed and style. boxedToRuled to false. 

♦ If this is prlnputPadStyleBoxed, the client would set an IP's style.diplayType to ipsCharBox and 
stylcboxedToRuled and style.ruledToBoxed to false. 

prWritingStyle: 

♦ Clients may want to let this preference affect the translation information they send with msgNew or 
the translator set with msglPSetTranslator. 

Single Character IPs 

clsIP has specific support for single character IPs. Setting style.charOnly to true enables this support. 
Usually if charOnly is true, then style.buttonType is ipsProxButton, style.takeGrab is true, and the 
client floats the IP rather than embedding it. 

Setting charOnly to true causes the IP to automatically set the number of rows and columns to 1. It also 
prepares the translator to expect only a single character. 

Debugging Flags 

IP's debugging flag set is 'h.' Defined flags are: 

0001 Show general information about IP operations. 

0002 Show information about IP translation operations. 
0004 Show information about IP layout and size operations. 

tifndef INSERTJENCLUDED 
tdefine INSERT_INCLUDED 
tifndef GO_INCLUDED 
♦include <go.h> 
tendif 
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Common #defines and typedefs 

#ifndef OSHEAP_INCLUDED 
#include <osheap.h> 
#endif 

#ifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

#endif 

#ifndef WIN_INCLUDED 

#include <win.h> 

#endif 

#ifndef CLAYOUT_INCLUDED 

tinclude <clayout.h> 

tendif 

// Next Up: 25 Recycled: 1, 2, 11, 12, 13 

Common #defines and typedefs 

typedef OBJECT IP; 5 

a. 

Z 

Display Types 

Use one of these values in an IP's style.displayType. This field defines the type of the IP. 
See the section "Typical Uses and Settings" for more information. 

tdefine ipsRuledLines // standard ruled lines; contains sPaper 

#define ipsCharBox 1 // character box editing; contains field 

tdefine ipsBlank 3 // signature pad; contains sPaper 

tdefine ipsSignature 3 // same as ipsBlank 

tdefine ipsCharBoxButtons 4 // Obsolete 

ipsEditBox Obsolete 

Translator types 

Use one of these values in an IP's style.xlateType. This field defines whether new.ip.xlate contains a 
template or a translator object. See the section "IPs and Translators" for more information. 

tdefine ipXlateObject // pNew->xlate. translator is a translator 

tdefine ipXlateTemplate 1 // pNew->xlate.pTemplate is an &XTEMPLATE 

Space Collapse Rules 

Use one of these values in an IP's style.spaceCollapse. For ipsCharBox IPs, this field defines how spaces 
are treated in text strings retrieved from an IP via msglPGetXlateData or msglPGetXlateString. 

ipsSpaceSpace causes multiple spaces at the end of a line to be replaced with a single space. 
ipsSpaceNewLine causes an entire line's worth of spaces to be replaced with a single newline character. 
ipsSpaceAsIs causes spaces to be returned literally. 

tdefine ipsSpaceAsIs // WYSIWYG 

tdefine ipsSpaceSpace 1 // Multiple spaces at end of line become 1 space 

tdefine ipsSpaceNewLine 2 // Single line of spaces becomes a newline 

Button Types 

Use one of these values in an IP's style.buttonType. This field defines the type of buttons an IP contains. 

ipsNo Button is typically used with displayType of ipsBlank. ipsProxButton is valid only with 
ipsRuledLines. This value cause translation to occur on out of proximity events. ipsBottomButtons and 
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ipsTopButtons create a command bar at the top or bottom containing an OK, Cancel, and Clear 
Button. 



tdefine ipsNoButton 

tdefine ipsProxButton 3 

tdefine ipsBottomButtons 6 

tdefine ipsTopButtons 7 



//No button 

// Proximity translation for ipsRuledLines 

// Command bar buttons on bottom 

// Command bar buttons on top 



Modality Behavior 

Use one of these values in an IP's style.modal. When style.takeGrab is true, style.modal defines the result 
of a pen tap outside of the IP. The term takeGrab is somewhat misleading. The IP actually creates a 
modal filter to handle input. 



tdefine ipsNoMode 

tdefine ipsTranslateMode 1 
tdefine ipsCancelMode 2 



// Nothing happens on pen tap outside 

// Translation happens on pen tap outside 

// Cancel happens if pen tap outside 



IP Style 



typedef struct IP_STYLE { 

U16 displayType: 3, 

buttonType: 3, 

freeAfter: 1, 

clientReplace : 1, 

xlateType: 1, 

charOnly: 1, 

modal : 2 , 

takeGrab : 

reservedl: 1, 

takeFocus: 1, 

delayed: 1; 

U16 spaceCollapse: 3, 

embeddedLook : 1 , 



reserved2: 1, 
ruledToBoxed : 1 , 



boxedToRuled: 



1, 



clientIsThisApp:l, 
reserved: 8; 
} IP STYLE, *P IP STYLE; 



// display type 

// button type 

// See the section "IP Destruction." 

// Unused 

// See the section "IPs and Translators." 

// Describes what pNew->ip.xlate contains. 

// See the section "Single Character IPs." 

// If style.takeGrab is true, describes modal 

// IP's behavior. 



1, // Makes the IP modal. Modal behavior is 

// defined by style.modal. 

// Reserved 

// IP becomes the input target when created. 

// For ipsCharBox IPs, turns on the field 

// component's delayed behavior. 

// Rule for collapsing spaces when 

// extracting information from ipsCharBox IP. 

// Set to true to look good when embedded; 

// false to look good when floating. Affects 

// an IP's handling of msgNew and msglPSetStyle. 

// Reserved 

// See the "Transmogrification" and "IPs and 

// Preferences" sections. 

// See the "Transmogrification" and "IPs and 

// Preferences" sections. 

// Private 

// Reserved 



Component Tags 



The components of an IP have the following window tags. See the section "IP Components" for more 
information. 

tdefine taglPSPaper 

tdefine taglPField 

tdefine taglPButton 

tdefine taglPButtonClear 

tdefine taglPButtonCancel 

tdefine taglPCommandBar MakeTag(clsIP, 6) // command bar 



MakeTag(clsIP, 


1) 


// 


ipsRuledLines and ipsBlank 






// 


IP's sPaper 


MakeTag(clsIP, 


2) 


// 


ipsCharBox IP's field 


MakeTag(clsIP, 


3) 


// 


"OK" button 


MakeTag(clsIP, 


4) 


// 


"Clear" button 


MakeTag(clsIP, 


5) 


// 


"Cancel" button 
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V w Quick Help Tags 

In most cases an IP component's window tag and quick help are identical. But taglPSignatureSPaper is 
the quick help tag for ipsBlank IP's sPaper and taglPSingleChar is the quick help tag of an IP with 
style.charOnly true. 

tdefine taglPSignatureSPaper MakeTag(clsIP, 7) 
#define taglPSingleChar MakeTag(clsIP, 8) 

|F Messages 

#ifndef NO_NEW 
tifndef ipNewFields 



msgNew 



Creates a new IP. a 

a. 

Takes IP_NEW, returns STATUS. 

// 

// Translation information. Notice that this is a union type. See the 

// section "IPs and Translators" for more information. 

// 

rgyments typedef union IP_XLATE { 

OBJECT translator; // xlateType = 0, clsXlate object 

PJJNKNOWN pTemplate; // xlateType = 1, P_XTEMPLATE 

} IP_XLATE, *P_IP_XLATE; 
typedef struct IP_NEW_ONLY { 

IP_STYLE style; //IP style 

IP_XLATE xlate; // See the section "IPs and Translators." 

// Translation information for the IP. 
U16 lineHeight; // Unused 

OBJECT client; // Client for notification messages. 

// See the section "Client and Observers." 
P_CHAR pString; // Initial string for ipsCharBox IP's field. 

U8 rows, cols; // Number of rows and cols in IP. Can 

// be zero if shrinkWrap is on. 
U16 lines; // Unused 

U16 xlndex; // Unused 

U32 reservedl; 

U16 maxLen; // Max string length IP can return. 

// means no limit. 
U32 reserved; 

} IP_NEW_ONLY, *P_IP_NEW_ONLY; 

tdefine ipNewFields \ 

customLayoutNewFields \ 
IP_NEW_ONLY ip; 

typedef struct IP_NEW { 

ipNewFields 
} IP_NEW, *P_IP_NEW; 

#endif // ipNewFields 
#endif // NO_NEW 

smmenfs In response to msgNew, clsIP creates the necessary components for the IP. This may include an instance 

of clsField, clsSPaper, or clsCommandBar. The various components are initialized according to the 
new.ip.style settings. 

The internal sPaper or field requires a translator. If xlateType is ipXlateObject, 
pNew->ip.xlate.translator is used as the translator object. If xlateType is ipXlateTemplate, then 
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pNew->ip.xlate.pTemplate is compiled and allocated at msgNew, and freed when the component is 
destroyed. See the section "IPs and Translators" for more information. 

border.style.bottomMargin is always bsMarginMedium. 

Finally, based on embeddedLook, msgNew changes the border style of the IP and the border and 
margin styles of the internal components to make the IP look good when embedded (embeddedLook 
true) or when floating (embeddedLook false). 

Defaults changed if embeddedLook is false: 

border. style. border Ink = bsInkGray66; 
border . style . leftMargin = bsMarginMedium; 
border . style . rightMargin = bsMarginMedium; 
border . style . topMargin = bsMarginMedium; 
border. style. backgroundlnk = bsInkGray33; 
border. style. shadow = bsShadowThickGray; 
win. flags. style |= wsSaveUnder; 

Defaults changed if embeddedLook is true: 

border. style. border Ink = bsInkGray33; 
border . style . leftMargin = bsMarginNone; 
border . style . rightMargin = bsMarginNone; 
border . style . topMargin = bsMarginNone; 
border. style. backgroundlnk = bsInkWhite; 
border. style. shadow = bsShadowThickWhite; 
win. flags. style &= ~wsSaveUnder; 

msgNewDefaults 

Initializes the IP_NEW structure to default values. 

Takes P_IP_NEW, returns STATUS. 

Message typedef struct IP_NEW { 

Arguments ipNewFields 

} IP_NEW, *P_IP_NEW; 

Comments When handling msgNew, certain border.style values are changed depending on the value of 

ip. embeddedLook. See msgNew for details. 

Zeros out pNew->ip and sets: 

ip.style.displayType = ipsRuledLines; 
ip. style. buttonType = ipsBottomButtons; 
ip. style. modal = ipsNoMode; 
ip. style. delayed = true; 
ip.maxLen = maxUl6; 

border . style . edge = bsEdgeAll; 
border. style. resize = bsResizeCorner; 
border. style. drag = bsDragDown; 
border. style. top = bsTopDrag; 

customLayout . style . limitToRootWin = true; 

win . flags . input | = 

(inputTip | inputChar | inputMultiChar | inputAutoTerm | \ 
inputlnProx | inputEnter | inputMoveUp | inputMoveDelta) ; 

win. flags. style |= wsSendGeometry; 

embeddedWin. style. moveable = false; 

embeddedWin . style . copyable = false; 
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msglPGetStyle 

Passes back the style of the IP. 
Takes P_IP_STYLE, returns STATUS. 

#define msglPGetStyle MakeMsg(clsIP, 5) 



nessoge 
Arguments 



typedef struct IP_STYLE { 



U16 displayType: 
buttonType : 
freeAfter: 
clientReplace : 
xlateType : 

charOnly : 
modal : 

takeGrab: 

reservedl : 
takeFocus : 
delayed: 

U16 spaceCollapse: 

embeddedLook : 



reserved2 : 
ruledToBoxed: 

boxedToRuled: 



3, 
3, 

1, 
1, 
1, 

1, 
2, 

1, 

1, 
1, 
1; 

3, 

1, 



1, 

1, 

1, 



clientIsThisApp:l, 
reserved : 8 ; 
} IP STYLE, *P IP STYLE; 



// display type 

// button type 

// See the section "IP Destruction." 

// Unused 

// See the section "IPs and Translators." 

// Describes what pNew->ip.xlate contains. 

// See the section "Single Character IPs." 

// If style. takeGrab is true, describes modal 

// IP's behavior. 

// Makes the IP modal. Modal behavior is 

// defined by style. modal. 

// Reserved 

//IP becomes the input target when created. 

// For ipsCharBox IPs, turns on the field 

// component's delayed behavior. 

// Rule for collapsing spaces when 

// extracting information from ipsCharBox IP. 

// Set to true to look good when embedded; 

// false to look good when floating. Affects 

// an IP's handling of msgNew and msglPSetStyle. 

// Reserved 

// See the "Transmogrification" and "IPs and 

// Preferences" sections. 

// See the "Transmogrification" and "IPs and 

// Preferences" sections. 

// Private 

// Reserved 



msglPSetStyle 

Changes the style of the IP. 

Takes P_IP_STYLE, returns STATUS. 

♦define msglPSetStyle MakeMsg(clsIP, 6) 



ftessGge 
Arguments 



typedef struct IP_STYLE { 

U16 displayType: 3, 

buttonType: 3, 

freeAfter : 1 , 

clientReplace: 1, 

xlateType: 1, 

charOnly : 1 , 

modal : 2 , 

takeGrab : 1 , 

reservedl: 1, 

takeFocus: 1, 

delayed: 1; 

U16 spaceCollapse: 3, 

embeddedLook : 1 , 



// display type 

// button type 

// See the section "IP Destruction." 

// Unused 

See the section "IPs and Translators." 

Describes what pNew->ip.xlate contains. 

See the section "Single Character IPs." 

If style. takeGrab is true, describes modal 

IP ' s behavior . 
// Makes the IP modal. Modal behavior is 
// defined by style. modal. 

Reserved 

IP becomes the input target when created. 
// For ipsCharBox IPs, turns on the field 
// component's delayed behavior. 
// Rule for collapsing spaces when 

extracting information from ipsCharBox IP. 

Set to true to look good when embedded; 



// 
// 
// 
// 
// 



// 
// 



// 
// 
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// false to look good when floating. Affects 

// an IP's handling of msgNew and msglPSetStyle . 
reserved2: 1, // Reserved 

ruledToBoxed: 1, // See the "Transmogrification" and "IPs and 

// Preferences" sections. 
boxedToRuled: 1, // See the "Transmogrification" and "IPs and 

// Preferences" sections. 
clientIsThisApp:l, // Private 
reserved: 8; // Reserved 

} IP_STYLE, *P_IP_STYLE; 

merits Clients use this message to change the style settings of an IP. Also, an IP self sends this message to 

perform transmogrification. 

In response to this message, an IP destroys obsolete components and creates new necessary ones. For 
example, changing from ipsCharBox to ipsRuledLines destroys the field component and creates an 
sPaper component. 

If an sPaper is being destroyed and a field being created, or vice versa, the IP extracts the translator 
information from the component about to be destroyed and moves it into the newly created one. 

This message dirties the layout the IP. 

This method does not change the IP's embeddedLook, xlateType, takeGrab, or takeFocus. 

msglPGetTranslator 

Passes back the translator for the IP. 

Takes P_OBJECT, returns STATUS. 

#define msglPGetTranslator MakeMsg(clsIP, 7) 

merits Passes back the translator for the IP, regardless of how it was created. An ipsBlank or ipsRuledLines IP 

passes back the translator used by the sPaper component. An ipsCharBox IP passes back the translator 
used by the field component. 

See the section "IPs and Translators" for more information. 



msglPSetTranslator 

Sets the translator for the IP. 

Takes P_OBJECT, returns STATUS. 

tdefine msglPSetTranslator MakeMsg(clsIP, 20) 

Use this message to set an IP's translator. 

In response to this message, a ipsCharBox IP sets its field's translator. Other IPs sets their sPaper s 
translator. All IPs change their style.xlateType to ipXlateObject. 

IMPORTANT: An IP does NOT free the current translation information in response to this message. 
The client must free this translation information. See the section "IPs and Translators" for more 
information. 

msglPGetClient 

Passes back the IP's client object in *pArgs. 

Takes P_OBJECT, returns STATUS. 

tdefine msglPGetClient MakeMsg(clsIP, 14) 
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Comments See the section "Client and Observers" for more information. 

See Also msglPSetClient 



Comments 
See Also 



msglPSetClient 

Makes pArgs the IP's client. 

Takes P_OBJECT, returns STATUS. 

♦define msglPSetClient MakeMsg(clsIP, 15) 

See the section "Client and Observers" for more information. 

msglPGetClient 



msglPSetString 

Sets a ipsCharBox IP's string. 
Takes P_CHAR, returns STATUS. 

tdefine msglPSetString MakeMsg(clsIP, 10) 

Comments Use this message to initialize or change the contents of a ipsCharBox IP. 

For ipsCharBox IPs, the default response to this message is to set the field component's string and to 
re-layout the IP. For other types of IPs, the default response is to return stsOK. 

See the section "IP Components" for more information. 

msglPTranslate 

Translates scribbles in an IP. 

Takes nothing, returns STATUS. 

tdefine msglPTranslate MakeMsg(clsIP, 3) 

Comments When pressed, the "OK" button of an IP's command bar sends this message to the IP. Also, a client can 

send this message to cause an IP to translate any scribbles. An IP also self sends this message (1) in 
response to msgGWinForwardedKey and (2) when a modal IP terminates the mode (style.takeGrab is 
true, style.modal is ipsTranslateMode, and the pen taps outside of the IP). 

The IP's response to this message is as follows. 

♦ ipsRuledLines and ipsBlank IPs send msgSPaperComplete to the IP's sPaper component. (The 
sPaper in turn sends msgSPaperXlateCompleted back to the IP; see the comments on 
msgSPaperXlateCompleted for IP's response.) 

♦ ipsCharBox IPs with style.delayed false self send msglPDataAvailable. 

♦ ipsCharBox IPs with style.delayed true and untranslated scribbles in the field first translate the 
scribbles and then self send msglPCopied. 

♦ ipsCharBox IPs with style.delayed true and no untranslated scribbles in the field self send 
msglPDataAvailable. 

pArgs must be 0. 

See Also msgSPaperXlateCompleted 



682 PENPOINT API REFERENCE 

Part 5 / Input and Handwriting 



msglPCancelled 

Cancels an IP. Also sent to notify observer/client about the cancel. 

Takes OBJECT, returns STATUS. 

#define msglPCancelled MakeMsg(clsIP, 18) 

Comments When pressed, the "Cancel" button of an IP's command bar sends this message to the IP. A client can 

also send this message to cause an IP to cancel itself. Also, msglPCancelled is sent to an IP's 
observers/client to notify them about the cancelling. 

msglPCancelled is also self sent if a modal IP has a style.modal value of ipsCancelMode and the modal 
IP is terminated (probably by a pen tap outside the IP). 

The IP's response to msglPCancelled is a follows. First the IP clears the component (field or sPaper) of 
any data it contains. Next, if the IP's style.rreeAfter is true, the IP extracts itself from the window- 
hierarchy and posts msgDestroy to itself. Finally, it sends msglPCancelled to observers/client to inform 
them of the cancellation. 

See the sections "IP Destruction" and "Client and Observers" for additional information. 

See Also msglPClear 

msglPClear 

Clears an IP's contents. Also sent to notify observers/client about the clearing. 

Takes OBJECT, returns STATUS. 

♦define msglPClear MakeMsg(clsIP, 23) 

Comments When pressed, the "Clear" button of an IP's command bar sends this message to the IP. A client can also 

send this message to cause an IP to clear its contents. Also, msglPClear is sent to an IP's observers/client 
to notify them about the clearing. 

An IP's response to msglPClear is as follows. If the IP has an sPaper component (ipsRuledLines or 
ipsBlank IP), then msgSPaperClear is sent to the sPaper. If the IP has a field component, and 
style.ruledToBoxed is false, then msgFieldClear is sent to the field. If the IP has a field and 
style.ruledToBoxed is true, then the IP transmogrifies itself to have an sPaper. Finally, msglPClear is 
sent to the IP's observers/client. 

See the sections "IP Components," "Client and Observers" and 'Transmogrification" for additional 
information. 



Also msglPCancelled (spaper.h)(field.h) 

Observer/Client Messages 



msglPCopied 

Notifies observer/client that newly translated data has been copied into a ipsCharBox IP's field. 

Takes OBJECT, returns STATUS. 

tdefine msglPCopied MakeMsg(clsIP, 19) 

See the section "Client and Observers" for additional information. 
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Data Retrieval Messages 



msglPDataAvailable 

Notifies observers/client that the IP has translated data available. 

Takes OBJECT, returns STATUS. 

#define msglPDataAvailable MakeMsg(clsIP, 16) 

Observers/clients can respond to this message by sending msglPGetXlateData or msglPGetXlateString 
to get the translated data. 

See the section "Client and Observers" for additional information. 

See Also msglPTranslate 



•omtnents 



msglPTransmogrified 

Notifies observers/client that the IP has been transmogrified. 

Takes OBJECT, returns STATUS. 2 

tdefine msglPTransmogrified MakeMsg(clsIP, 24) 

See the sections 'Transmogrification" and "Client and Observers" for additional information. 

msglPTranslate 



Data Retrieval Messages 



msglPGetXlateData 

Passes back translated data in xlist form. 

Takes P_IP_XLATE_DATA, returns STATUS. 

tdefine msglPGetXlateData MakeMsg(clsIP, 4) 

Arguments typedef struct IP_XLATE_DATA { 

OS_HEAP_ID heap; // In: heap for xlist allocation. 

P_UNKNOWN pXList; // Out: pointer to resulting xlist. 

} IP_XLATE_DATA, *P_IP_XLATE_DATA; 

Comments The default response to msglPGetXlateData is as follows. 

An xlist is created in pArgs->heap (or osProcessHeapId if pArgs->heap is null.) Then the xlist is filled 
in as follows. 

♦ An ipsCharBox IP's xlist contains an xtBounds followed by an xtText element. The IP's field is 
cleared (using msgFieldClear; see field.h). (The bounds is artificially constructed.) 

♦ An ipsRuledLines IP's xlist contains the xlist returned by sending msgSPaperGetXlateData (see 
spaper.h) to the sPaper component of the IP. 

♦ This message should not be sent to a ipsBlank IP because no translation is ever performed by this 
type of IP. 

If the IP's style.freeAfter is true, then the IP self destructs; see the section "IP Destruction" for details. 

If self is a ipsCharBox IP and style. boxedToRuled is true, then the IP transmogrifies into a 
ipsRuledLines IP. See the 'Transmogrification" section. 

If self is a ipsCharBox IP, then the space collapse rules defined in style. spaceCollapse are applied to the 
xtText element in the xlist. 
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IMPORTANT: The sender of msglPGetXlateData must free the returned xlist and elements in the 
xlist. (See xlist.h in general and XListFree() in particular.) 

Ms& msglPTransmogrified.h.h 

msglPGetXlateString 

Passes back translated data in string form. 

Takes P_IP_STRING, returns STATUS. 

imenfs typedef struct IP_STRING { 

U16 len; // In-Out: length of buffer pointed to by pString 

P_CHAR pString; // In-Out: buffer pointer 

} IP_STRING, *P_IP_STRING; 
#define msglPGetXlateString MakeMsg(clsIP, 17) 

menfs In response to this message, an IP passes back its translated contents as a simple string form. 

Clients should use this message rather msglPGetXlateData if a simple string is needed. Clients should 
use msglPGetXlateData if the additional information contained in an xlist is needed. 

If pArgs->len is maxU16, the IP allocates the necessary string memory from the process heap. The 
sender of msglPGetXlateString must free this memory. 

The returned pArgs->pString is "clipped" to pArgs->maxLen. The actual number of characters returned 
is returned in pArgs->len. 

Note: The handler of this message first self sends msglPGetXlateData to get an xlist and then converts 
the data xlist to a string. See the comments regarding msglPGetXlateData for information on the IP's 
self destruction and transmogrification. 

Also msglPGetXlateData 



Messages from Other Classes 



msgFree 

Defined in clsmgr.h. 
Takes P_OBJ_KEY, returns STATUS. 
Comments The IP sends msgFree to its components. It then frees any translation information passed into msgNew. 

See the section "IPs and Translators" for more information. 

msgSave 

Defined in clsmgr.h. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments The IP saves all necessary state and uses the window hierarchy filing mechanism to save any 

components. 

If the IP's client is OSThisAppQ, this is remembered. See msgRestore for more information. 
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Messages from Other Classes 



msgWinStartPage 

Defined in win.h. 

Takes nothing, returns STATUS. 

Comments Only sophisticated subclasses might want to handle this message. This message informs an IP that it 

exists on a printer and that printing is about to commence. 

If the IP is not ipsBlank, an IP's default response is to return stsOK. Otherwise, the IP turns off all of its 
own margins and all of the borders and ruling lines for the sPaper component. This causes the IP to 
print only the scribbles, which is particularly appropriate when an IP has been used to capture and hold 
a signature. 



3 



msgRestore 

Defined in clsmgr.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments clsIP restores self and uses the window hierarchy filing mechanism to restore any components. clsIP 

then re-establishes the necessary connections between self and each component. 

If the IP's client was OSThisAppO when saved, then the IP's client becomes OSThisAppO; otherwise 
the client becomes to objNull. 

See Also win.h 

msgSetOwner 

Defined in clsmgr.h. 

Takes P_OBJ_OWNER, returns STATUS. Z 

Comments An IP lets its superclasses respond to this message and then sends msgSetOwner to its components. 

See the section "IP Components" for more information. 

msgSPaperXlateCompleted 

Defined in spaper.h. 

Takes OBJECT, returns STATUS. 

Comments Only sophisticated subclasses might want to handle this message. An IP with an sPaper component 

(ipsRuledLines and ipsBlank) receives this message from the sPaper when the sPaper has completed 
translation. 

If style. ruledToBoxed is false, this message simply self sends msglPDataAvailable. Otherwise the IP tries 
to transmogrify itself, using the following steps: 

♦ The translated string is extracted from the sPaper component. 

♦ If the string is empty, the IP self sends msglPDataAvailable and gives up the effort to transmogrify. 

♦ The IP transmogrifies itself. 

In both cases, the sPaper component (if it still exists) is cleared. 
See the 'Transmogrification" section. 

See Also msglPTranslate 
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msgGWinForwardedKey 

Defined in gwin.h. 

Takes PJNPUTJEVENT, returns STATUS. 

Only sophisticated subclasses might want to handle this message. A child window may send this message 
when the child receives a keyboard input event that it doesn't want to handle. 

If the key's keyCode is uKeyReturn (see key.h), the IP self sends msglPTranslate. Otherwise it returns 
stsRequestForward. 

Sent when a component (field) forwards a key. An IP containing a field component that forwards the 
Return key causes msglPTranslate to be self sent, as if the "OK" button was pressed. 

msglPTranslate.h.h 



msglnputTargetActivated 

Defined in input.h. 

Takes OBJECT, returns STATUS. 

Only sophisticated subclasses might want to handle this message. The input system sends this message 
to an object to inform an object that it is no the input target. 

In response to this message, an IP remembers the previous input target. If the IP is a ipsCharBox IP, it 
makes the IP's field the input target. 

The IP restores the previous input target as part of its response to msgWinExtracted. 



msgTrackProvideMetrics 

Defined in track.h. 

Takes P_TRACK_METRICS, returns STATUS. 

Comments Only sophisticated subclasses might want to handle this message. 

clsIP is a descendant of clsBorder. Unless turned off by a subclass, an IP is resizeable by the user. When 
clsBorder creates a resize object and its associated tracker, it first self sends msgTrackProvideMetrics to 
allow itself to modify the parameters of the tracker. 

In response to this message, an IP does the following: 

♦ If the tracker is not a resizing tracker, the IP simply returns stsOK. 

♦ The IP remembers the original client of the tracker so that the IP can forward tracker-related 
messages onto that original client. It then makes itself be the client of the tracker. 

♦ If the IP has a command bar (style.buttonType is ipsBottomButtons or ipsTopButtons), then 
pArgs->style.draw is set to tsDrawCmdBarRect and pArgs->cmdBarH is set appropriately. 

♦ The tracker's minimum size constraints are adjusted so that the IP can get no smaller than the 
scribbles that are in the IP's field or sPaper. This prevents scribbles from being covered. 

♦ The IP the makes itself the client of the tracker so that the IP receives msgTrackUpdate and 
msgTrackDone. 

See Ais© msgTrackUpdate 
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Obsolete 



msgTrackUpdate 

Defined in track.h. 

Takes P_TRACK_METRICS, returns STATUS. 
Comments Only sophisticated subclasses might want to handle this message. 

The default response to this message is to forward the message to the tracker's original client, as 



remembered in msgTrackProvideMetrics. 
See Also msgTrackProvideMetrics 



msgTrackDone 

Defined in track.h. 

Takes P_TRACK_METRICS, returns STATUS. D 

a. 

Only sophisticated subclasses might want to handle this message. 

ipsBlank IPs can be resized to any size. Otherwise the default response to this message is to force the 
new size of the IP to fit nicely around whole rows and columns (in ipsCharBox IPs) or lines (in 
ipsRuledLines IPs). Then the message is forwarded to the tracker's original client, as remembered in 
msgTrackProvideMetrics. 

msgTrackProvideMetrics 



Obsolete 



#define stsIPNotSupported MakeStatus (clsIP, 1) // Obsolete 
tdefine stsIPBadMode MakeStatus (clsIP, 2) // Obsolete 
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KEY.H 



This file contains the API definition for the keyboard driver. 

clsKey inherits from clsObject. 

The functions described in this file are contained in INPUT.LIB. 

This file defines the data sent with keyboard event. Keyboard events are generated by both the real 
keyboard and the virtual keyboard. 

Keyboard Events 

When keyboard devices (physical or virtual) generate input events, the events are delivered via 
msglnputEvent. The following are the value of pArgs->devCode for msglnputEvent. 

msgKeyDown sent when a key is depressed. 

msgKeyUp sent when a key is released. 

msgKeyChar contains an individual character code and is sent when a key is depressed. 

msgKeyMulti contains multiple character codes that have accumulated since the last msgKeyMulti 
event was sent. This allows processing of multiple keys without the overhead of a separate message 
for each key. For all of these values, pArgs->eventData should be cast to P_KEY_DATA. (A 
msgKeyMulti event contains the same information as several msgKeyChar events.) 



Input Flags 



Keyboard events can be enabled or disabled using input flags. See input.h for more information. The 
relevant flags for keyboard events are: 



input flag 



enables 



inputChar msgKeyChar 

inputMultiChar msgKeyMulti 

inputMakeBreak msgKeyUp and msgKeyDown 

Clients should still verify that the devCode is the particular message they are interested in. 



Sample Code 



You can verify that your msglnputEvent handler is handling a keyboard message by checking as follows: 
if (ClsNum(pArgs->devCode) == ClsNum (clsKey) ) { 

} 

You should further verify that the devCode is the particular message that you are interested in 
processing. 

Once you've decided that you're looking at a key event, you can cast pArgs->eventData as follows: 

P_KEY_DATA pKeyData; 

pKeyData = (P_KEY DATA) (pArgs->eventData) ; 
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This example shows how you might handle msglnputEvent with a devCode of msgKeyUp, 
msgKeyDown or msgKeyChar: 

for (i=0, i<pKeyData->repeatCount; i++) { 

HandleSingleKey (pKeyData->keyCode, pKeyData->shift State) ; 

} 

This example shows how you might handle msglnputEvent with a devCode of msgKeyMulti: 

P_KEY_MULTI pMulti = pKeyData->multi; 
for (i=0, i<pKeyData->repeatCount; i++) { 

for (j=0; j<pMulti[i] .repeatCount; j++) { 

HandleSingleKey (pMulti [i] .keyCode, pKeyMulti [i] . shiftState) ; 
} 
} 
#ifndef KEY_INCLUDED 
#define KEY_INCLUDED 

#ifndef GO_INCLUDED 
#include <go.h> 
#endif 

#ifndef UID_INCLUDED 
#include <uid.h> 
#endif 

tifndef OSHEAP_INCLUDED 

#include <osheap.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

#endif 



Keyboard Event Messages 



#define msgKeyUp MakeMsg(clsKey, 0) 

tdefine msgKeyDown MakeMsg(clsKey, 1) 

tdefine msgKeyChar MakeMsg(clsKey, 12) 

tdefine msgKeyMulti MakeMsg(clsKey, 13) 

Common #defines and typedefs 

Shift Flags 

These are used in the shiftState field of KEY_MULTI and KEYJDATA. They indicate which modifier keys 
were down when the event was generated. 

tdefine keyScrollLock flagO 

tdefine keyNumLock flagl 

tdefine keyCapsLock flag2 

tdefine keyShift flag3 

tdefine keyCtrl flag4 

tdefine keyAlt flag5 

tdefine keyLeftShift flag6 

tdefine keyRightShift flag7 

tdefine keyLeftCtrl flag8 

tdefine keyRightCtrl flag9 

tdefine keyLeftAlt flagl 

tdefine keyRightAlt flagl 1 

tdefine keyShiftLock f lagl2 

tdefine keyCtrlLock flagl3 

tdefine keyAlt Lock flagl 4 



KEY.H 
Common #dofines and typedefs 
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Pjr Key Codes 




Special ASCII characters 




tdefine uKeyBackSpace 


0x08 


tdefine uKeyTab 


0x09 


tdefine uKeyLineFeed 


0x0a 


#define uKeyReturn 


OxOd 


#define uKeyEscape 


Oxlb 


Keys with no ASCII values; mapp 


tdefine uKeyFl 


OxfOOl 


tdefine uKeyF2 


0xf002 


#define uKeyF3 


0xf003 


tdefine uKeyF4 


0xf004 


tdefine uKeyF5 


0xf005 


tdefine uKeyF6 


0xf006 


tdefine uKeyF7 


0xf007 


tdefine uKeyF8 


0xf008 


tdefine uKeyF9 


0xf009 


tdefine uKeyFlO 


OxfOOa 


tdefine uKeyFll 


OxfOOb 


tdefine uKeyF12 


OxfOOc 


tdefine uKeylnsert 


0xf020 


tdefine uKeyDelete 


0xf021 


tdefine uKeyHome 


0xf022 


tdefine uKeyEnd 


0xf023 


tdefine uKeyPageUp 


0xf024 


tdefine uKeyPageDown 


0xf025 


tdefine uKeyUp 


0xf026 


tdefine uKeyDown 


0xf027 


tdefine uKeyLeft 


0xf028 


tdefine uKeyRight 


0xf029 


tdefine uKeyCenter 


0xf02a 


tdefine uKeyPrintScreen 


0xf02b 


tdefine uKeyPause 


0xf02c 


tdefine uKeySysRq 


0xf02d 


tdefine uKeyBreak 


Oxf 02e 


tdefine uKeyBackTab 


0xf02f 



msglnputEvent Argument Types 

KEY_MULTI holds the variable length data for msglnputEvent with a devCode of msgKeyMulti. 



typedef struct KEY_MULTI { 

U16 keyCode; 

U16 scanCode; 

U16 shiftState; 

U16 repeatCount; 

U8 reservedA[4] ; 
} KEY_MULTI, *P_KEY_MULTI; 

KEY_DATA is the "true" type of msglnputEvent's pArgs->eventData for all keyboard event messages. 

If msglnputEvent's pArgs->devCode is msgKeyMulti, the keyCode, scanCode and shiftState fields of 
this struct are undefined. Each of these fields is defined in a KEY_MULTI struct. 



// ASCII value 

// keyboard scan code 

// state of the shift, ctrl & alt keys 

// number of autorepeats to apply 

// reserved for future use 



typedef struct KEY_DATA { 
U16 keyCode; 
U16 scanCode; 
U16 shiftState; 
Ul 6 repeatCount ; 



U8 reserved [24] 
KEY_MULTI multi[l]; 
KEY DATA, *P KEY DATA; 



// ASCII key translation 

// keyboard scan code 

// state of the shift, Ctrl & alt keys 

// if not msgKeyMulti, the no. of identical 

// keycodes received. If msgKeyMulti, the 

// number of KEY_MULTI structs in multi. 

// if msgKeyMulti, an array of KEY MULTIs 
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KEYBOARD.H 



Interface to the software keyboard class. Keyboards do NOT file. 

clsKeyboard inherits from clsKeyCap. 

Provides the standard keyboard look and interaction. 

clsKeyboard inherits from clsKeyCap and provides keyboard-like 

behavior. It directly supports the standard QWERTY keyboard and the PC 101 key keyboard layout 
and display. Other forms of keyboards can be generated by overriding the keycap layout table. 

The make/break interface is implemented through a call-back procedure. This routine is setup in the 
new parameters and is called with the standard keyboard messages: msgKeyMake, msgKeyBreak, 
msgKeyChar, and msgKeyMulti. 

The scan code mapping table is generally reusable for most keyboard layouts. 

WARNING: These API's are not currently in a suitable state for developers. 

#ifndef KEYBOARD_INCLUDED 
#define KEYBOARD_INCLUDED 

#ifndef GO_INCLUDED 

# include <go.h> 

#endif 

#ifndef OSHEAP_INCLUDED 

tinclude <osheap.h> 

#endif 

#ifndef UID_INCLUDED 

#include <uid.h> 

tendif 

#ifndef KEY_INCLUDED 

# include <key.h> 

#endif 

#ifndef KEYCAP_INCLUDED 

#include <keycap.h> 

#endif 

#ifndef KEYSTATE_INCLUDED 

tinclude <keystate.h> 

#endif 

Quick Help Ids 

This is the quick help Id for keyboard objects. 

#define tagKeyboard MakeTag (clsKeyboard, 1) 

Class Messages 

msgNewDefaults 

Initializes the default new arguments. 
Takes P_KEYBOARD_NEW, returns STATUS. 
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jments typedef Struct KEYBOARD_NEW_ONLY { 

P_U16 pMap; // scan code to key map 

P_KEYSTATE_PROC pProc; // proc for processing events 

P_UNKNOWN pUserData; // user data for the proc 

} KEYBOARD_NEW_ONLY, *P_KEYBOARD_NEW_ONLY ; 

#define keyboardNewFields \ 

keyCapNewFields \ 

KEYBOARD_NEW_ONLY keyboard; 

typedef struct KEYBOARD_NEW { 

keyboardNewFields ' 

} KEYBOARD_NEW, *P_KEYBOARD_NEW; 

ments The default settings are: 

pArgs->keyboard.pMap = PC 101 keyboard mapping 
pArgs->keyboard.pProc = pNull; 
pArgs->keyboard.pUserData = NULL; 

msgNew 

Creates a new keyboard object. 

Takes P_KEYBOARD_NEW, returns STATUS. 

fessage typedef struct KEYBOARD_NEW { 

Arguments keyboardNewFields 

} KEYBOARD_NEW, *P_KEYBOARD_NEW; 

msgKeyboardReturn 

Handles completion of processing of a key event. 

Takes P_KEYBOARD_RET, returns STATUS. 

irgwnersis typedef struct KEYBOARDJRET { 

MESSAGE msg; // message 

P_KEY_DATA pKey; // key information, see key.h 

} KEYBOARD_RET, *P_KEYBOARD_RET; 
#define msgKeyboardReturn MakeMsg(clsKeyboard, 1) 

:©«n»efits This message is only needed by the virtual keyboard application. 

Standard Keyboard Events 

msgKeyMake 

Self call & notification of make key. 
Takes P_KEY_DATA, returns STATUS. 



msgKeyBreak 

Self call & notification of break key. 
Takes P_KEY_DATA, returns STATUS. 
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msgKeyChar 

Self call & notification of character event. 
Takes P_KEY_DATA, returns STATUS. 



msgKeyMulti 

Self call & notification of multi-key event. 
Takes P_KEY_DATA, returns STATUS. 
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KEYCAP.H 



Interface for the KeyCap class. 

clsKeyCap inherits from clsWin. 

Provides an array of keycaps for keyboard emulations. 

clsKeyCap inherits from clsWin which provides support for an array 

of keyboard "caps" which can deliver a scan code and make/break events. Subclasses are expected to 
added the glyph which is displayed on the cap when the key is painted. This is accomplished by 
intercepting the self-call msgKeyCapPaintCap. 

WARNING: These API's are not currently in a suitable state for developers. 

#ifndef KEYCAP_INCLUDED 

#define KEYCAP_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

#ifndef OSHEAP_INCLUDED 

#include <osheap.h> 

#endif 

#ifndef UID_INCLUDED 

#include <uid.h> 

tendif 

#ifndef WIN_INCLUDED 

#include <win.h> 

#endif 

#define maxCaps 150 // max for the KEYCAP_TABLE declaration 



Cap Width Descriptors 

A data table based mechanism is used to define the array of key caps. Each row is a fixed height 
(determined by dividing the window by the number of rows). Each cap can have one of five widths, 
small, medium, large, extra large and huge. A small cap is the basic unit of measure, all other cap sizes 
are multiples of this size. This size is determined by dividing the window width by the number of switch 
units. The cap sizes are: small = 1 unit, medium =1.5 units, large = 2 units, extra large = 2.5 units, and 
huge = 7 units. 



tdefine kcEND 
#define kcS 
#define kcM 
#define kcL 
tdefine kcX 
#define kcH 



(0x0000) 
(0x1000) 
(0x2000) 
(0x3000) 
(0x4000) 
(0x5000) 

typedef struct KEYCAPJTABLE { 
U16 rows; 
U16 switches; 
U16 capCodes[maxCaps] ; 



} KEYCAP TABLE, *P KEYCAP TABLE; 



// end of row marker 

// small cap 

// medium cap 

// large cap 

// extra large cap 

// huge cap 

// number of rows 

// number of column units 

// array of scan codes with 

// cap width descriptor (high nibble) 

// Each row must end with kcEnd and 

// the table must end with two 

// kcEnd tokens. 
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Glass Messages 



msgNewDefaults 

Initializes the new arguments. 

Takes P_KEYCAP_NEW, returns STATUS. 

typedef struct KEYCAP_NEW_ONLY { 

P_KEYCAP_TABLE pTable; // pointer to the keycap table 
} KEYCAP_NEW_ONLY, *P_KEYCAP_NEW_ONLY; 

#define keyCapNewFields \ 

OBJECT_NEW_ONLY object; \ 

WIN_NEW_ONLY win; \ 
KEYCAP_NEW_ONLY keyCap; 

typedef struct KEYCAP_NEW { 

keyCapNewFields 
} KEYCAP_NEW, *P_KEYCAP_NEW; 

The pTable field is initialized to pNull by default. 

msgNew 

Creates a new instance of the keycap object. 

Takes P_KEYCAP_NEW, returns STATUS. 

typedef struct KEYCAP_NEW { 

keyCapNewFields 
} KEYCAP_NEW, *P_KEYCAP_NEW; 

If the pTable pointer is NULL, the standard QWERTY layout is used by default. 



msgKeyCapPaintCap 

Hook to allow painting on top of keycap. 

Takes P_KEYCAP_INFO, returns STATUS. 

Arguments typedef struct KEYCAP_INFO { 

U16 scanCode; // scan code for the keycap 

RECT32 rect; // location of the keycap rect, LWC 

BOOLEAN hilite; // TRUE for highlighted display 

OBJECT dc; // Drawing context 
} KEYCAP_INFO, *P_KEYCAP_INFO; 

#define msgKeyCapPaintCap MakeMsg(clsKeyCap, 1) 

Comments This is the self-call hook which allows subclasses the ability to paint the glyph on the keycap. This call is 

made during the response to msgWinRepaint and is therefore already bracketed by 
msgWinBeginRepaint, msgWinEndRepaint. 

msgKeyCapScan 

Locates the keycap under a given x,y. 

Takes P_KEYCAP_SCAN, returns STATUS. 

Arguments typedef struct KEYCAP_SCAN { 

XY32 xy; // coordinates for search 

U16 scanCode; // Out: scan code of keycap 

RECT32 rect; // Out: keycap rect in LWC 

} KEYCAP_SCAN, *P_KEYCAP_SCAN; 
#define msgKeyCapScan MakeMsg(clsKeyCap, 2) 

Comments This function returns the keycap which is under the Local Window Coordinates (LWC) xy. 
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msgKeyCapGetDc 

Returns the DC used by the keycap. 

Takes P_KEYCAP_GET_DC, returns STATUS. 

Arguments typedef struct KEYCAP_GET_DC { 

OBJECT dc; // Out: keycap dc object 

} KEYCAP_GET_DC, *P_KEYCAP_GET_DC; 
♦define msgKeyCapGetDc MakeMsg(clsKeyCap, 3) 



msgKeyCapRedisplay 

Forces the display to be regenerated. 

Takes nothing, returns STATUS. 

tdefine msgKeyCapRedisplay MakeMsg(clsKeyCap, 5) 



msgKeyCapHilite z 

Hilites the key with the given scan code. 
Takes P_KEYCAP_HILITE, returns STATUS. 

Arguments typedef Struct KEYCAP_HILITE { 

U16 scan; // In: scan code to hilite 

BOOLEAN on; // In: true to display as hilite 

} KEYCAP_HILITE, *P_KEYCAP_HILITE; 
tdefine msgKeyCapHilite MakeMsg(clsKeyCap, 6) 

Comments The key cap object tracks which keys (by scan code) are highlighted at any given time. 

msgKeyCapMake 

Subclass hook to indicate button press of keycap. 

Takes P_KEYCAP_INFO, returns STATUS. 

tdefine msgKeyCapMake MakeMsg(clsKeyCap, 0x80) 

message typedef struct KEYCAP_INFO { 

Arguments ui6 scanCode; // scan code for the keycap 

RECT32 rect; // location of the keycap rect, LWC 

BOOLEAN hilite; // TRUE for highlighted display 

OBJECT dc; // Drawing context. 
} KEYCAP_INFO, *P_KEYCAP_INFO; 

Comments This message is a self-call when the pen touches down on a keycap. Note that only one make/break 

event pair is generated for each penDown, penUp combination. Sliding off a key onto another is NOT 
considered a press on the new key. 

msgKeyCapBreak 

Subclass hook to indicate button release of keycap. 

Takes P_KEYCAP_INFO, returns STATUS. 

tdefine msgKeyCapBreak MakeMsg(clsKeyCap, 0x81) 

Message typedef Struct KEYCAP_INFO { 

Arguments U16 scanCode; // scan code for the keycap 

RECT32 rect; // location of the keycap rect, LWC 

BOOLEAN hilite; // TRUE for highlighted display 

OBJECT dc; // Drawing context 
} KEYCAP_INFO, *P_KEYCAP_INFO; 

Comments This message is a self-call when the pen is lifted up from the previous make event. 
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Interface for the hardware independent keyboard code interpreter 

WARNING: These API calls are not currently in a state suitable for developer use. 

#ifndef KEYSTATE_INCLUDED 
tdefine KEYSTATE_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

fendif 

#ifndef OSHEAP_INCLUDED 

#include <osheap.h> 

#endif 

#ifndef KEY_INCLUDED 

tinclude <key.h> 

#endif 

tdefine keyMultiMax 16 // max # multi-key buffered events 
typedef void (PASCAL *P_KEYSTATE_PROC) (PJJNKNOWN, MESSAGE, P_KEY_DATA) ; 

typedef struct KEYSTATE { 

U16 state; 

U16 last Scanned; 

U16 last Sent; 

U16 count; 

SI 6 onHold; 

SI 6 multi; 

P_U16 pMap; 

S16 multilndex; 

P_KEY_MULTI pBuffer; 

P_KEYSTATE_PROC pKeyEvent ; 

P_UNKNOWN pUserData; 
} KEYSTATE, *P KEYSTATE; 



// keyboard decode state 

// long-term state flags 

// last scan code processed 

// last scan code sent 

// count of repeated codes while on Hold 

// number of character events to be processed 

// number of multi-char events " 

// pointer to the scan-to-char map 

// index into the multi-key array 

// buffer for multi-key recording 

// proc. pointer for reporting keystate changes 
data for use by the user proc. 



// 



fur 



KeyStateSetup 

Initializes a state structure to quiesent values. 

Returns nothing. 

void PASCAL KeyStateSetup ( 
P_KEYSTATE pState 

); 



KeyStateProcess 

Converts the scan code into the appro riate action for shift keys and standard keys. 
Returns nothing. 



Function Prototype void PASCAL KeyStateProcess ( 
P_KEYSTATE pState, 
U16 scanCode 
); 



// pointer to the keyboard state structure 
// scan code to process 
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KeyStateConvert 

Converts a scan code to the appropriate character code, or sets up the appropriate shift state. 
Returns nothing. 

void PASCAL KeyStateConvert ( 

P_KEYSTATE pState, // pointer to the keyboard state structure 

U16 scanCode, // scan code to convert 

P_U16 pChar, // character code 

P_U16 pDisplay // display charactere code 
); 



KeyStateReturn 

Process completion of the key event. 

Returns nothing. 

type void PASCAL KeyStateReturn ( 
P_KEYSTATE pState, 
MESSAGE msg, 
P_KEY_DATA pKey 
); 

KeyStateFindScan 

Returns the scan code for a shift state flag. 
Returns nothing. 

typedef struct KEYSTATE_SCANS { 

U16 count; // In: max count, Out: actual count 

U16 scanCodes[4] ; // can be variable number of entries 

} KEYSTATE_SCANS, *P_KEYSTATE_SCANS; 

type void PASCAL KeyStateFindScan ( 

P_KEYSTATE pState, // pointer to the keyboard state structure 
U16 state, // state flag for search 

P_KEYSTATE_SCANS pScanCode // Out: scan code 
); 

KeyStateDisplay 

Returns the set of display codes for the scan code. 

Returns nothing. 

typedef struct KEYSTATE_CODES { 

U16 count; // In: max count, Out: actual count 

struct { 

U16 shift; 
U16 charCode; 
} data [4]; // can be variable number of entries 

} KEYSTATE_CODES, *P_KEYSTATE_CODES; 

void PASCAL KeyStateDisplay ( 

P_KEYSTATE pState, // pointer to the keyboard state structure 
U16 scanCode, // scan code to be converted 

P_KEYSTATE_CODES pCodes // Out: scan code 

); 
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PEN.H 



This file contains the API definition for the pen driver. 

clsPen inherits from clsObject. 

The functions described in this file are contained in INPUT.LIB. 

This file contains information about pen-generated input events. See input.h for general information on 
PenPoint's input system and input events. You should probably read at least the "Road Map" section of 
input.h before trying to understand this file in detail. 

Pen Events 

When the pen generates input events, the events are delivered via msglnputEvent. The following values 
are the value of pArgs->devCode for msglnputEvent. 

msgPenUp sent when the pen tip is lifted from the screen. 

msgPenDown sent when the pen tip touches the screen. 

msgPenMoveUp sent as the pen moves while above the screen and in proximity. 

msgPenMoveDown sent as the pen moves while touching the screen. 

msgPenEnterUp sent when the pen enters a window while above the screen and in proximity. 

msgPenEnterDown sent when the pen enters into a window while touching the screen. 

msgPenExitUp sent when the pen exits a window while above the screen and in proximity. 

msgPenExitDown sent when the pen exits a window while touching the screen. 

msgPenlnProxUp sent when the pen comes into proximity. This message is also sent when certain 
timeouts occur; see the section "Proximity Timeout Events" for more information. 

msgPenOutProxUp sent when the pen leaves proximity. This message is also sent when certain 
timeouts occur; see the section "Proximity Timeout Events" for more information. 

msgPenStroke sent with the collected stroke data. See the "Stroke Events" section. 

msgPenTap sent when taps are recognized by the driver. See the 'Tap Events" section. The taps field of 
PEN_DATA contains the number of taps. 

msgPenHoldTimeout sent after pen down and hold timeout. See the "Hold Timeout Events" section. 
The taps field of PEN_DATA contains the number of taps that occurred before the Hold. 

[Terminology Note: the msgPenlnProxUp and msgPenOutProxUp events can be thought of as 
msgPenlnProx and msgPenOutProx since the pen tip is always up when these events are sent. The 
trailing "Up" is present for historical reasons only.] 
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Input Flags 

Pen events can be screened out using input flags. See input.h for more information. The relevant flags 
for pen are: 

input flag enables see section 



input Tip 

inputMoveUp 

inputMoveDown 

inputEnter 

inputExit 

inputlnProx 
input OutProx 
inputStroke 
input Tap 
inputHoldTimeout 



msgPenUp 

msgPenDown 

msgPenMoveUp 

msgPenMoveDown 

msgPenEnterUp 

msgPenEnterDown 

msgPenExitUp 

msgPenExitDown 

msgPenlnProxUp 

msgPenOutProxUp 

msgPenStroke 

msgPenTap 

msgPenHoldTimeout 



"Hold Timeout Events' 



Enter Exit Window Events 

msgPenEnterUp, msgPenEnterDown, msgPenExitUp and msgPenExitDown are generated when the 
pen transits a window boundary. The window that the pen was previously in will receive msgPenExitUp 
or msgPenExitDown (if its input flags request them). The window that the pen is now in will receive 
msgPenEnterUp or msgPenEnterDown (if its input flags request them). Note that if the pen leaves 
proximity, the window will receive a msgPenOutProxUp and not msgPenExitUp. Similarly, if the pen 
enters proximity, the window will receive msgPenlnProxUp and not msgPenEnterUp. 

The timestamp, strokeSeqNum and penXY field of the PEN_DATA structure will be valid. All other 
fields will be 0. 

Hold Timeout Events 

msgPenHoldTimeout events are generated when the user puts the pen on the display and leaves it there 
for the "Hold" timeout duration. This message is also generated if the user taps 1 or more times before 
holding the pen down. 

For example, msgPenHoldTimeout is the event that triggers PenPoint's move and copy, and is also used 
by some applications to trigger wipe-through area selection. 

msgPenHoldTimeout events are sent if the window's input flags have the inputHoldTimeout flag set. 

The strokeSeqNum field of the PEN_DATA structure will be the sequence number of the most recent pen 
down. The penXY field of the PEN_DATA structure will be the pen device coordinates of the first pen 
down. 

will be valid. All other fields will be 0. 



Proximity Timeout Events 

The input system also has a proximity-related timeout. These are used if the user lifts the pen off the 
display but leaves the pen in proximity. 

This timer is typically used to trigger translation because some users don't lift their pen tips out of 
proximity but still want translation to occur. 
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If this timer expires with the pen still in proximity, the input system sends msgPenOutProxUp, followed 
by msgPenlnProxUp. In other words, the input system generates events to make it look like the user 
temporarily lifted the pen out of proximity. 

[Note: the obsolete messages msgPenTimeout and msgPenHWTimeout are not sent.] 

Stroke Events 

Each time the pen goes down, moves, and comes up, the input system generates msglnputEvent with a 
pArgs->devCode of msgPenStroke. The pArgs also includes a compressed representation of the stroke. 

One way to think about a stroke event is as a "summary" or "reprise" of msgPenDown, zero or more 
msgPenMoveDowns, and a msgPenUp. 

Stroke events are delivered to the window in which the stroke started (if that window has the input flag 
inputStroke flag set), even if the stroke crosses that window's boundaries. 

Stroke events are generated in addition to the other, lower level, messages that occur as the stroke event 
is being accumulated. Typical clients either handle msgPenStroke or the lower-level messages 
(msgPenDown, msgPenMoveDown, msgPenUp), but NOT both. 

The input system assigns a sequence number to each stroke. Each pen event contains the stroke number 
that the event is a part of. This number is found in the "strokeSeqNum" field of PEN_DATA. 

See the "Sample Code" section for an example of how to extract stroke information from the pArgs of a 
stroke event. 

Tap Events 

A msgPenTap is generated if there is a msgPenDown followed by a msgPenUp and (1) any pen motion 
between the Down and Up is below some threshold and (2) the Down and Up happen within a certain 
time interval and (3) the Down and Up occur over the same window and (4) no other input event 
(excepting an optional Out of Proximity) event happens within a certain time threshold of the Up. 

msgPenTap is sent if the input flag inputTap is set. 

If the pen is "tapped" repeatedly, a single msgPenTap is sent and the taps field of PEN_DATA contains 
the number of pen taps. 

The strokeSeqNum field of the PEN_DATA structure will be the sequence number of the most recent pen 
down. The penXY field of the PEN_DATA structure will be the pen device coordinates of the first pen 
down. 

Typical Sequences of Events 

This sections illustrates some typical sequences of pen events. It does not include tap, timeout and stroke 
events. It also does not show forwarding up the window parent chain. 

This table contains the flow of events if the pen comes down, moves around, and comes back up, all 
within a single window. 

quantity event 



1 


msgPenlnProxUp 


or more 


msgPenMoveUp 


1 


msgPenDown 


or more 


msgPenMoveDown 


1 


msgPenUp 


or more 


msgPenMoveUp 


1 


msgPenOutProxUp 
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This sequence is complicated if the pen crosses a window boundary while moving. When this happens, 
the input system generates Enter and Exit events to notify the windows being entered and exited. In the 
following example, assume that the window hierarchy isn't changing and that the pen crosses a window 
boundary between windows A and B while the pen is down. 



quantity 


events seen by A 


events seen by B 


1 


msgPenlnProxUp 




or more 


msgPenMoveUp 




1 


msgPenDown 




or more 


msgPenMoveDown 




1 


msgPenExitDown 




1 




msgPenEnterDown 


1 




msgPenUp 


or more 




msgPenMoveUp 


1 




msgPenOutProxUp 



If the pen goes down in window A and in response window A "pops up" a window B right where the 
pen is, and the user lifts the pen, the following sequence occurs: 

quantity events seen by A events seen by B 



1 


msgPenlnProxUp 




or more 


msgPenMoveUp 




1 


msgPenDown 




1 


msgPenExitDown 




1 




msgPenEnterDown 


1 




msgPenUp 


or more 




msgPenMoveUp 


1 




msgPenOutProxUp 



Sample Code 



You can verify that your msglnputEvent handler is handling a pen message by checking as follows: 

if (ClsNum(pArgs->devCode) == ClsNum(clsPen) ) { 

Once you've decided that you're looking at a pen event, you can cast pArgs->eventData as follows: 

P_PEN_DATA pPenData; 

pPenData = (P_PEN_DATA) (pArgs->eventData) ; 

If pArgs->devCode is msgPenStroke, you can get a pointer to the stroke data as follows: 

P_PEN_STROKE pSt roke ; 

pStroke = (P_PEN_STROKE) ( (P_PEN_DATA) (pArgs->eventData) ) ->data; 
#ifndef PEN_INCLUDED 
#define PEN_INCLUDED 

#ifndef GO_INCLUDED 
linclude <go.h> 
#endif 

tifndef GEO_INCLUDED 
♦include <geo.h> 
tendif 

tifndef INPUT_INCLUDED 
tinclude <input.h> 
#endif 
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msglnputEvent 


Argument Types 


ent Messages 








#define msgPenUp 


MakeMsg(clsPen, 


event TipUp) 




#define msgPenDown 


MakeMsg (clsPen, 


eventTipDown) 




tdefine msgPenMoveUp 


MakeMsg (clsPen, 


eventMoveUp) 




#define msgPenMoveDown 


MakeMsg (clsPen, 


e ventMoveDown ) 




#define msgPenEnterUp 


MakeMsg (clsPen, 


eventEnterUp) 




#define msgPenEnterDown 


MakeMsg (clsPen, 


eventEnterDown) 




#define msgPenExitUp 


MakeMsg (clsPen, 


event Exit Up) 




#define msgPenExitDown 


MakeMsg (clsPen, 


eventExitDown) 




tdefine msgPenlnProxUp 


MakeMsg (clsPen, 


eventlnProxUp) 




#define msgPenOutProxUp 


MakeMsg (clsPen, 


eventOutProxUp) 




#define msgPenStroke 


MakeMsg (clsPen, 


event Stroke) 




tdefine msgPenTap 


MakeMsg (clsPen, 


event Tap) 




tdefine msgPenHoldTimeout 


MakeMsg (clsPen, 


eventHoldTimeout ) 
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Common #defines and typedefs 

All pen events report coordinates in standard pen resolution, which units of 0.1 mm. 

tdefine penStdResolution 10000 // lines per meter 

Possible states of the pen tip. 

typedef U16 PEN_TIP_STATE_FLAGS, *P_PEN_TIP_STATE_FLAGS; 
tdefine penOutOfProximity 
tdefine penlnProximity flagO 
tdefine penTipDown flagl 

Possible states of the pen tip. 

Enuml6(PEN_TIP_STATE_TYPE) { 

penTipOutOfProxState = 0, 

penTipInProxState = 1, 

penTipDownState = 2 
}; 

typedef U16 PEN_SUPPORTS_FLAGS , 
tdefine penSupportsProximity 
tdefine penSupportsPressure 
tdefine penSupportsZPosition 
tdefine penSupportsZAngle 
tdefine penSupportsXYAngle 
tdefine penSupportsPenld 
tdefine penSeparateFromScreen 

tdefine penDatalsStroke 
tdefine penSupportsInk 
tdefine penSupportsStrokes 



PEN SUPPORTS 


_FLAGS; 


flagO 






flagl 


// 


For future use. 


flag2 


// 


For future use. 


flag3 


// 


For future use. 


flag4 


// 


For future use. 


flag5 


// 


For future use. 


flag6 


// 


digitizer is not 




// 


integrated with display 


flag7 


// 


For future use. 


flagl2 


// 


For future use. 


flagl3 


// 


For future use. 



msglnputEvent Argument Types 

PEN_DATA is the "true" type of msglnputEvent s pArgs->eventData for all pen event messages. 

timeStamp time the event occurred, as defined by the pen driver. This may differ from 
pArgs->timeStamp, which is time the event was enqueued by the input system. 

strokeSeqNum Number of the stroke that this event is in. See the section "Stroke Events" for more 
information. 

taps if pArgs->devCode is msgPenHoldTimeout this field contains the number of taps that occurred 
before the hold. If pArgs->devCode is msgPenTap, this field contains the tap count. 
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data Variable length data. Contents depends on the msglnputEvent's pArgs->devCode. For instance, if 
pArgs->devCode is msgPenStroke, then this field is the beginning of the event's stroke information. 

typedef struct PEN_DATA { 



// in 0.1 iran pen units 

// For future use. 

// For future use. 

// For future use. 

// For future use. 

// For future use. 

// one of PEN_TIP_STATE_FLAGS 

// start of variable length data 



PEN_STROKE holds the variable length data for msglnputEvent with a devCode of msgPenStroke. See 
the section "Stroke Events" for more information. It holds the stroke data. It consists of header 
information followed by the compressed XY data. 

The stroke data can be converted into other useful forms using the functions described in the section 
"Stroke Manipulation Functions." 



U32 








timestamp; 


P UNKNOWN 








reservedPointer; 


U32 








strokeSeqNum; 


XY16 








penXY; 


PEN SUPPORTS 


_FLAGS 


penSupportsFlags ; 


S16 








pressure; 


S16 








zPosition; 


U16 








penld; 


S16 








xy Angle; 


S16 








zAngle; 


U16 








reserved [1] ; 


U8 








tipState; 


U8 








taps ; 


U8 








data[l]; 


} PEN_DATA, *P_ 


_PEN_ 


_DATA 





typedef struct PEN_STR0KE { 

RECTI 6 bounds; 

U16 count; 

U16 id; 

struct 
{ 
U16 len:15, 

selected: 1; 
} info; 

U8 data[l]; 

} PEN STROKE, *P PEN STROKE; 



// bounds in pen coordinates 

// number of points 

// stroke id when added to scribble 



III bytes in the data field 
// used by scribble object 

// byte array of compressed points 



Other Types 



typedef struct CURRENT STD PEN DATA { 



xPosition; 

yPosition; 

penTipState; 

zPosition; 

pressure; 

penld; 

xyAngle ; 

zAngle ; 

posit ionAcetate; 

*P CURRENT STD PEN DATA; 



S16 
S16 

PEN_TIP_STATE_TYPE 
U16 
U16 
U16 
U16 
U16 
XY32 
} CURRENT_STD_PEN_DATA, 

typedef struct PEN_METRICS { 

U32 minResolution; 

U32 maxResolution; 

U32 currentResolution; 

U32 maxXPosition; 

U32 maxYPosition; 

U32 xPosition; 

U32 yPosition; 

U32 deviceFlags; 

U32 reservedU32[2]; 

PEN_TIP_STATE_FLAGS penTipState; 
PEN_SUPPORTS_FLAGS penSupportsFlags ; 



// in 0.1 mm pen units 
// in 0.1 mm pen units 

// For future use. 

// For future use. 

// For future use. 

// For future use. 

// For future use. 



// lines per 
// lines per 
// lines per 
// using pen 
// using pen 
// using pen 
// using pen 



meter 

meter 

meter 

resolution 

resolution 

resolution 

resolution 



U16 
U16 
U16 
U16 
U16 
U16 
U16 



lowSampleRate; 
medSampleRate; 
highSampleRat e ; 
current SampleRate ; 
reportingThreshold; 
deviceld; 
reservedU16[4] ; 



} PEN METRICS, *P PEN METRICS; 



Messages 



PEN.H 
Stroke Manipulation Functions 



// using pen resolution 
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msgPenMetrics 

Sent to thePen. thePen passes back the current pen device metrics. 

Takes P_PEN_METRICS, returns STATUS. 

tdefine msgPenMetrics MakeMsg(clsPen, OxFE) 



lessasge 
krqymenfs 



typedef struct PEN_METRICS { 

U32 minResolution; 

U32 maxResolution; 

U32 currentResolution; 

U32 maxXPosition; 

U32 maxYPosition; 

U32 xPosition; 

U32 yPosition; 

U32 deviceFlags; 

U32 reservedU32[2]; 

PEN_TIP_STATE_FLAGS penTipState ; 

PEN_SUPPORTS_FLAGS penSupport sFlags ; 

U16 lowSampleRate; 

U16 medSampleRate; 

U16 highSampleRate; 

U16 current SampleRate; 

U16 reportingThreshold; 

U16 deviceld; 

U16 reservedUl6[4]; 

} PEN METRICS, *P PEN METRICS; 



Stroke Manipulation Functions 



// lines per meter 

// lines per meter 

// lines per meter 

// using pen resolution 

// using pen resolution 

// using pen resolution 

// using pen resolution 



// using pen resolution 



Function Pre 



Comments 



PenExpander 

Decompresses a point from the compressed stroke structure. 

Returns SI 6. 

S16 PASCAL PenExpander (P_U8 pData, P_S16 pX, P_S16 pY) ; 

pX and pY must point to the previous point value. (They must be set to the bounding box origin for the 
first point). The new point is passed back using the same pointers. 

The return value is the number of bytes to advance pData to get to the next point. 

PenStrokeRetrace 

Iterates the points in a compressed stroke structure. 
Returns SI 6. 

typedef void (PASCAL * P_DRAW_PROC) (PJJNKNOWN, S16, S16) ; 
FytKtiosi Prototype S16 PASCAL PenStrokeRetrace ( 
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P PEN STROKE 


pStroke, 


P DRAW PROC 


pProc, 


S16 


xOff, 


S16 


yoff, 


P UNKNOWN 


appData 



); 



// ptr to the stroke structure 

// ptr to a function to process the points 

// x base offset 

// y base offset 

// application specific data 



PenStrokeUnpackl 6 

Expands a compressed stroke to an array of XY16. 
Returns STATUS. 



Function Prototype STATUS PASCAL PenStrokeUnpackl 6 ( 



P PEN STROKE 


pStroke, 


P XY32 


pBase, 


P XY16 


pBuffer, 


BOOLEAN 


toLWC 



); 



// compressed stroke 

// stroke window offset 

// point buffer 

// true to transform points to LWC 



Miction PK 



Function Prototype 



"omments 



PenStrokeUnpack32 

Expands a compressed stroke to an array of XY32. 
Returns STATUS. 



STATUS PASCAL PenStrokeUnpack32 ( 
P_PEN_STROKE pStroke, 
P_XY32 pBase, 
P_XY32 pBuffer, 
BOOLEAN toLWC 

); 



// compressed stroke 

// stroke window offset 

// point buffer 

// true to transform points to LWC 



XY16ToPenStroke 

Converts an array of XY16 values to into a PEN_STROKE. 

Returns STATUS. 

STATUS EXPORTED XY16ToPenStroke ( 

XY16 pPointDataf], // In: XY point data 

U16 numPoints, // In: number of points in pPointData 

OS_HEAP_ID heapld, // In: heap to allocate stroke from 

P_PEN_STROKE *ppNewPenStroke // Out: pointer to new pen stroke 

); 

The function allocates memory for the PEN_STROKE from heapld. If pPointData is null or numPoints 
is then only the PEN_STROKE data structure is allocated. 



PenCurrentStandardData 

Fills in the most recent pen data in standard units. 
Returns nothing. 

Function Prototype void PASCAL PenCurrentStandardData (P CURRENT STD PEN DATA pPenStdData) ; 
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SCRIBBLE.H 



This file contains the API definition for clsScribble. 

clsScribble inherits from clsObject. 

Instances of clsScribble (or scribbles for short) store pen strokes. Scribbles also interact with translators. 

Introduction 

An scribble is a collection of pen strokes. Clients can add strokes to (and remove strokes from) a 
scribble. Clients can use msgScrRender to render a scribble in a given drawing context. 

A client typically adds strokes to a scribble during the client's response to msgPenStroke type input 
events. 

clsScribble is a relatively low-level piece of PenPoint. Many clients can and should use clsGWin 
(gwin.h) or clsSPaper (spaper.h) rather than clsScribble. 



Coordinates and the Base 

A scribble's coordinates are in Pen Units. (See msgDcUnitsPen in sysgraf.h.) 

Each scribble has a "base." By default, a scribble's base is the origin of the first stroke added to the 
scribble (via msgScrAddStroke). Whenever a stroke is added to a scribble, the scribble's base is 
subtracted from the origin of the stroke before the stroke is made part of the scribble. In other words, all 
strokes are stored relative to the scribble's base. This allows repositioning the entire scribble by adjusting 
the base. For instance, the client might do this in response to a window resize operation to keep the 
scribble in the "same" position relative to the upper left corner of a window. 

This base is not transparent when extracting a stroke from a scribble. When using msgScrStrokePtr to 
get a pointer to a stroke in a scribble, it is necessary to add the scribble base back to the stroke origin in 
order to get the original stroke origin. 

Adding Strokes to Scribbles 

This example shows how strokes are added to a scribble by a window that is handling msglnputEvent 
when pArgs->devCode is msgPenStroke. Note that pArgs->base is set to the origin of the scribble. 

// msgPenStroke' s stroke data arrives in root window- relative device 

// units. Convert the stroke data to be self -relative. Steps: 

// (1) Compute the origin of self relative to the root window, 

// (2) Convert that origin to pen units. 

wm. parent = theRootWindow; 

wm. child = NULL; 

wm. bounds. origin. x = 0; 

wm. bounds. origin. y = 0; 

wm. bounds. size. h = 0; 

wm. bounds. size. w = 0; 

ObjectCall(msgWinTransformBounds, self, &wm) ; 

ConvertOriginToPenCoordinates (&wm. bounds .origin) ; 
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// Now add the scribble to the stroke. Note that the scrAdd.base is 
// the base (i.e., origin) of the STROKE, not the scribble. 
scrAdd.base.x = pStroke->bounds . origin. x - wm. bounds. origin. x; 
scrAdd.base.y = pStroke->bounds. origin. y - wm. bounds. origin. y; 
ObjectCall(msgScrAddStroke, scribble, fiscrAdd) ; 

This code gives a rough idea of how a scribble adds a stroke in response to msgScrAddStroke. This is 
provided so that you can see how the base is used. Basically, the base of the scribble is subtracted from 
pArgs->base and used as the origin of the stroke. 

// Make a local copy of the stroke. Then convert the stroke's origin 

// to be relative to the scribble's base. 

pNewStroke = <Copy of pArgs->pStroke>; 

pNewStroke->bounds. origin. x = pArgs->base.x - scribble. base. x; 

pNewStroke->bounds . origin. y = pArgs->base.y - scribble. base. y; 

Odd stroke to internal data structures> 

Repositioning Scribbles 

To reposition a scribble, (1) compute the delta by which you want to move the scribble, (2) get the 
scribbles current base using msgScrGetBase, (3) add the delta to the current base, and (4) set the base 
using msgScrSetBase. Be sure to use msgScrSetBase since it will readjust the bounds of the scribble. 

Debugging Flags 

clsScribble uses the debugging flag set 'h'. Defined flags are: 

0100 General scribble debugging information 

0800 Scribble save and restore debugging information 

Limitations 

Strokes in a scribble must be within ((2 A 15)-1) units of each other. 

Memory for deleted strokes is only recovered upon msgScrClear. No other messages recover deleted 
stroke memory. Deleted strokes are saved and restored. 

#ifndef SCRIBBLE_INCLUDED 
♦define SCRIBBLE_INCLUDED 

#ifndef GO_INCLUDED 
tinclude <go.h> 
tendif 

tifndef OSHEAP_INCLUDED 

#include <osheap.h> 

tendif 

#ifndef GEO_INCLUDED 

tinclude <geo.h> 

tendif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef PEN_INCLUDED 

tinclude <pen.h> 

tendif 

tifndef DEBUG_INCLUDED 

tinclude <debug.h> 

tendif 

// Next Up: 18 Recycled: 2, 7, 8, 
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Messages Defined by Other Classes 

Common #defines and typedefs 

typedef OBJECT SCRIBBLE; 

stsScrOutOfRange is returned from msgScrAddStroke if the coordinates for the base of the scribble are 
out of the allowable range for strokes. 

tdefine StsScrOutOfRange MakeStatus (clsScribble, 1) 

Messages Defined by Other Classes 

msgNew 

Creates and initializes a new scribble. 

Takes P_SCR_NEW, returns STATUS. Category: class message. 



msgNewDefaults 

Sets the default values for the new arguments. 
Takes P_SCR_NEW, returns STATUS. 

typedef struct SCR_NEW_ONLY { 

XY32 base; // initial base value, default (0,0) 

U32 reserved; // reserved for future use 

} SCR_NEW_ONLY; 

#define scribbleNewFields \ 
OBJECT_NEW_ONLY object; \ 
SCR_NEW_ONLY scribble; 

typedef struct SCR_NEW { 

scribbleNewFields 
} SCR_NEW, *P_SCR_NEW; 

Zeros out pNew->scribble. 

msgFree 

Defined in clsmgr.h 

Takes P_OBJ_KEY, returns STATUS. 

The scribble frees all of its strokes. 



msgSave 

Defined in clsmgr.h. 
Takes P_OBJ_SAVE, returns STATUS. 
Comments Saves all strokes to pArgs->file. 

msgRestore 

Defined in clsmgr.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

Restores all strokes from pArgs->file. 
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msgPicSegPaintObject 

Defined in picseg.h. 

Takes P_PIC_SEG_OBJECT, returns STATUS. 

ments In response to this message, a scribble paints itself. Any object which responds to msgPicSegPaintObject 

can be placed into a PicSeg (and instance of clsPicSeg). 

Messages 

msgScrSetBase 

Sets the scribble's base. 

Takes P_XY32, returns STATUS. 

#define msgScrSetBase MakeMsg(clsScribble,ll) 

Recomputes the bounds of the scribble to reflect the new base. 

See the section "Coordinates and the Base" for more information. 

msgScrGetBase 

Passes back the base for the scribble. 

Takes P_XY32, returns STATUS. 

tdefine msgScrGetBase MakeMsg(clsScribble, 10) 

See the section "Coordinates and the Base" for more information. 

msgScrGetBounds 

Passes back the bounds of the scribble. 

Takes P_RECT32, returns STATUS. 

tdefine msgScrGetBounds MakeMsg(clsScribble, 12) 

Passes back the bounding box that contains all the strokes in the scribble. The bounding box is in pen 
units. 

msgScrCount 

Passes back the number of strokes in the scribble. 

Takes P_U16, returns STATUS. 

tdefine msgScrCount MakeMsg(clsScribble,l) 

msgScrAddStroke 

Adds a stroke to the scribble. 

Takes P_SCR_ADD_STROKE, returns STATUS. 

tdefine msgScrAddStroke MakeMsg(clsScribble,3) 

typedef struct SCR_ADD_STROKE { 

XY32 base; // In: origin of the stroke. 

P_PEN_STROKE pStroke; // In: pointer to stroke data 

U16 index; // Out: index of the newly added stroke 

} SCR ADD STROKE, * P SCR ADD STROKE; 



SCRIBBLE. H 715 

Messages 

Comments In response to this message, the scribble makes a copy of the stroke data and adds the stroke to itself. 

Observers are notified with msgScrAddedStroke. Note the SCR_ADD_STROKE base is the base (i.e., 
origin) of the STROKE. 

If this is the first stroke to be added to the scribble, the scribble's base is set to pArgs->base. Otherwise 
the base of the stroke is shifted by the scribble base as follows: 

stroke. bounds. origin = pArgs->base - scribble. base; 
Return Value stsScrOutOfRange The computed base for the stroke was out of the allowable range. 



msgScrDeleteStroke 

Deletes the stroke from the scribble. 

Takes U16, returns STATUS. 

#define msgScrDeleteStroke MakeMsg(clsScribble,4) 

Comments In response to this message, the scribble marks as deleted the stroke with the index value of pArgs. 

Observers receive msgScrRemovedStroke. 

Note: this does not actually free any memory, the scribble is just marked as deleted. 

See Ais© msgScrRemovedStroke 

msgScrDeleteStrokeArea 

Deletes all of the strokes in the scribble which intersect pArgs->rect. 

Takes P_SCR_DELETE_STROKE_AREA, returns STATUS. 

#define msgScrDeleteStrokeArea MakeMsg(clsScribble, 2) 

Arguments typedef struct SCR_DELETE_STROKE_AREA { 

RECT32 rect; // Rectangle of area to delete strokes from. 

// In pen units. 
OBJECT window; // Window to dirty 

U32 spare; // Reserved. 

} SCR_DELETE_STROKE_AREA, *P_SCR_DELETE_STROKE_AREA; 

Comments The scribble uses msgScrHit and msgScrDeleteStroke to do the deletions. Observers receive one 

msgScrRemovedStroke for each intersecting stroke. 

If pArgs->window is non-null, the scribble dirties the appropriate rectangle in the window. 

See Also msgScrHit 



msgScrCat 

Adds (concatenates) the strokes from another scribble to self. 

Takes SCRIBBLE, returns STATUS. 

tdefine msgScrCat MakeMsg(clsScribble,6) 

Comments The receiving scribble makes copies of all of the strokes in the pArgs scribble and adds them to itself by 

self sending msgScrAddStroke. 

See Also msgScrAddStroke 
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msgScrComplete 

Sent to a scribble to indicate completion. 

Takes void, returns STATUS. 

tdefine msgScrComplete MakeMsg(clsScribble, 5) 

Clients send this message to a scribble to tell the scribble that it is "complete." The client is responsible 
for determining when a scribble is complete. (For instance, the client might decide that a scribble is 
complete when the client receives an out-of-proximity pen event, or when a certain amount of time has 
elapsed since the last input event.) 

A scribble does nothing in response to this message except to send msgScrCompleted to all observers. 

A translator is a typical observer of a scribble. See xlate.h for information about how a translator 
responds to msgScrCompleted. 

msgScrCompleted 

msgScrStrokePtr 

Passes back the pointer to the stroke identified by pArgs->index. 

Takes P_SCR_STROKE_PTR, returns STATUS. 

#define msgScrStrokePtr MakeMsg(clsScribble, 9) 

typedef struct SCR_STROKE_PTR { 

U16 index; // In: index to the stroke 

P_PEN_STROKE pStroke; // Out: pointer to the index' th stroke, or 

// pNull if no such stroke exists. 

} SCR_STROKE_PTR, *P_SCR_STROKE_PTR; 

Be Careful! pArgs->pStroke is a pointer to internal data, not a copy. 

Strokes retrieved from scribbles are relative to the scribble's base. The stroke's origin is NOT the same as 
was passed to msgScrAddStroke ~ you need to add the scribble's base back. Note that this may still not 
be the same as the original stroke origin if the scribble base has been adjusted. 

msgScrClear 

Deletes all the strokes in the scribble. 

Takes void, returns STATUS. 

♦define msgScrClear MakeMsg(clsScribble, 15) 

In response to this message, the scribble sets its stroke count to zero, scribble's stroke count to 0. It also 
frees all allocated memory. 

Important: Observers are not notified! 

msgScrRender 

Renders a scribble in a window through a DC. 

Takes P_SCR_RENDER, returns STATUS. 

#define msgScrRender MakeMsg(clsScribble,13) 



U16 


stop; 


XY32 


base; 


OBJECT 


dc; 


RECT32 


rect ; 
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Notifications Sent to Observers 

Arguments typedef struct SCR_RENDER { 

U16 start; // stroke start index (0 for first) 

// stroke stop index (maxU16 for last) 

// unused 

// dc for rendering the stroke 

// dirty rect 
} SCR_RENDER, *P_SCR_RENDER; 

Comments Draws the strokes in the scribble using pArgs->dc. The start and stop indices describe the inclusive range 

of strokes to be rendered. Only strokes intersecting pArgs->rect are rendered. pArgs->rect must be in 
window device coordinates. pArgs->dc must be set up to draw in pen coordinates (using 
msgDcUnitsPen as described in sysgraf.h). 

msgScrHit 

Passes back the next stroke which intersects pArgs->rect. 

Takes P_SCR_HIT, returns STATUS. 

#define msgScrHit MakeMsg(clsScribble,14) 

Arguments typedef struct SCR_HIT { 

RECT32 rect; // In: rect to test against, in pen coordinates. 

U16 index; // In: For the first send, should be 0. Do 

// not disturb between sends. Out: if 

// pArgs->hi is true, the index of the next 

// stroke that intersects pArgs->rect. 

BOOLEAN hit; // Out: true if another stroke intersect 

// pArgs->rect; false when no more strokes 

// intersect. 
} SCR_HIT, *P_SCR_HIT; 

Comments This message is typically sent multiple times to find all strokes that intersect pArgs->rect. The hit-test is 

quite simple -- a stroke "intersects" if the stroke's bounding box intersects pArgs->rect. 

Clients should set pArgs->index to before first sending this message and then not disturb that field 
between sends. 

If a hit is found, pArgs->hit is true and pArgs->index is the stroke index. Otherwise pArgs->hit is false. 

Example: 

P_SCR_HIT hit; 

hit. rect = <rect to check> 

hit. index =0; 

hit. hit = TRUE; 

while (hit. hit) { 

Ob jectCall (msgScrHit, scribble, &hit); 

if (hit. hit) { 

// hit. index now equals the first stroke that intersected 

} 
} 



Notifications Sent to Observers 



msgScrCompleted 

Notifies observers that scribble input has been completed. 

Takes NULL, returns STATUS. 

tdefine msgScrCompleted MakeMsg(clsScribble, 0x80) 
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Comments This notification is sent as part of a scribble's response to msgScrComplete. 

Typical use: Translators that are observing the scribble may perform their translation in response to this 
message. (See xlate.h for more information.) 

msgScrAddedStroke 

Notifies observers that a stroke has been added to the scribble. 

Takes P_SCR_ADDED_STROKE, returns STATUS. 

#define msgScrAddedStroke MakeMsg(clsScribble, 0x81) 

typedef struct SCR_ADDED_STROKE { 

U16 index; // index of the added stroke 

P_PEN_STROKE pStroke; - // pointer to the stroke data structure 

} SCR_ADDED_STROKE, *P_SCR_ADDED_STROKE; 

This notification sent as part of a scribble's response to msgScrAddStroke. 

msgScrRemovedStroke 

Notifies observers that a stroke has been removed from the scribble. 

Takes P_SCR_REMOVED_STROKE, returns STATUS. 

#define msgScrRemovedStroke MakeMsg(clsScribble, 0x82) 

typedef struct SCR_REMOVED_STROKE { 

U16 index; // index of the removed stroke 

U16 id; // stroke identifier 

RECT32 bounds; // bounds of the removed stroke (in pen units) 

} SCR_REMOVED_STROKE, *P_SCR_REMOVED_STROKE; 

This notification is sent as part of a scribble's response to msgScrDeleteStroke. 
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SPAPER.H 



This file contains the API definition for clsSPaper. 

clsSPaper inherits from clsView. 

An instance of clsSPaper (or sPaper, for short) provides stroke redisplay, very simple stroke editing, and 
translation. 



Road Map 



A typical sPaper client simply creates an sPaper with self as the listener. The client than handles the 
msgSPaperXlateCompleted notification and uses msgSPaperGetXlateData to extract the resulting data. 

Clients or subclasses who wish to get involved in the sPaper s management of strokes might use: 

♦ msgSPaperClear 

♦ msgSPaperAddStroke 

♦ msgSPaperDeleteStrokes 

Clients or subclasses who wish to be involved in controlling when translation is triggered might use: 

♦ msgSPaperComplete 

♦ msgSPaperAbort 

If a client only needs translation, the client may not need to use sPaper at all. The client may be able to 
use translators (xlate.h) and scribbles (scribble.h) directly. 



SPaper Components 



An sPaper manages a translator and a scribble. The sPaper observes the the translator and the translator 
observes the scribble. 

The sPaper has a listener which is specified when the sPaper is created. An sPaper makes the listener an 
observer of the sPaper. As a result, the listener receives sPaper notifications. 



Typical Scenario 



The usual scenario for an spaper follows. The spaper is created and inserted onto the screen. The spaper 
receives pen strokes which it passes on to its scribble which in turn passes them on to a translator. At 
some point, the spaper is "complete" either via an external notification or optionally when an out of 
proximity event is received. The spaper notifies the scribble and the scribble notifies the translator. 
When the translator is complete, it notifies the spaper which in turn notifies its listener. The listener 
then asks the spaper for the translated data and the spaper gets the data from the translator. 

Here's a typical flow of messages between the sPaper, its scribble, its translator and the sPaper s listener. 
(This scenario uses messages defined in input.h, pen.h, xlate.h and scribble.h) 
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When the sPaper receives a msglnputEvent that contains a stroke (see pen.h) it self sends 
msgSPaperAddStroke, which sends msgScrAddStroke to the scribble. 

input system — > msglnputEvent — > sPaper 

sPaper — > msgScrAddStroke — > scribble 

The scribble then sends msgScrAddStroke to its observers. One of the scribble's observers is the sPaper s 
translator. 

scribble — > msgScrAddStroke — > translator 

Eventually sPaper receives msgSPaperComplete. (A client may send msgSPaperComplete to the 
sPaper. Alternatively, depending on the sPaper's flags, the sPaper may self send msgSPaperComplete. 
For example, see the description of the spProx flag elsewhere in this file.) In response to 
msgSPaperComplete, the sPaper sends msgScrComplete to the scribble. In turn, the scribble notifies its 
observers (including the translator) with msgScrCompleted. 

sPaper — > msgScrComplete — > scribble 

scribble — > msgScrCompleted — > translator 

The translator responds to msgScrCompleted by sending msgXlateCompleted to its observers, which 
include the sPaper. The sPaper responds to msgXlateCompleted by sending 
msgSPaperXlateCompleted to its observers, which include the listener. 

translator — > msgXlateCompleted — > sPaper 

sPaper — > msgSPaperXlateCompleted — > listener 

The listener typically sends msgSPaperGetXlateData to the sPaper to retrieve the translated data. In 
response to msgSPaperGetXlateData, the sPaper sends msgXlateData to the translator. 

listener — > msgSPaperGetXlateData — > sPaper 

sPaper — > msgXlateData — > translator 

Debugging Flags 

clsSPaper uses the debugging flag set 'h\ Defined flags are: 
0010 General sPaper debugging information 
0020 sPaper translation debugging information 
0080 sPaper save and restore debugging information 



Relationship to dsGWin 



Although sPaper is a descendent of clsGWin, it inherits little of clsGWin's behavior. All input and 
translation behavior is overridden. 

#ifndef SPAPER_INCLUDED 
♦define SPAPER_INCLUDED 
tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 

tifndef UID_INCLUDED 
tinclude <uid.h> 
tendif 

tifndef OSHEAP_INCLUDED 
tinclude <osheap.h> 
tendif 

tifndef WINJENCLUDED 
tinclude <win.h> 
tendif 
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Common #defines and typedefs 



tifndef VIEW_INCLUDED 

tinclude <view.h> 

#endif 

// Next Up: 24 Recycled: 1, 5, 9, 12 Used: 128 

Common #defines and typedefs 

typedef OBJECT SPAPER; 



Flags 



These flags are set in pNew->sPaper.flags field, and can be manipulated using msgSPaperSetFlags and 
msgSPaperGetFlags . 

♦ spCapture. If false, the sPaper destroys an existing scribble and creates a new one when the first 
stroke since the last translation is received. If true, the scribble is preserved between translations. See 
the "SPaper Components" section for more information. 

♦ spProx. If true, the sPaper self sends msgSPaperComplete when msgPenOutProxUp is received. In 
effect, setting this flag causes the sPaper to spontaneously translate when an "out of proximity" 
event occurs. 

♦ spFixedPos. If true, the sPaper keeps the top-left corner of its scribble fixed distance from the 
top-left corner of self during a resize operation. 

♦ spPenCoords. If true, xlists returned by the sPaper have pen coordinate rather than LWC 
coordinates. 

♦ spGrab. If true, the sPaper grabs input in response to msgPenDown and releases the grab in 
response to msgSPaperAbort or msgSPaperComplete. 

♦ spScribbleEdit. If true (the default), allows the user to delete scribbles via scratch out. sPaper 
implements a VERY rudimentary "scratch out" gesture. If spScribbleEdit is true and the user draws 
just the right "scratch out" gesture the strokes under the gesture are deleted. This does NOT use 
PenPoint's general gesture translation facilities. 

♦ spRedisplay. If true (the default), the sPaper redisplays its scribble's strokes whenever anything 
changes. 

♦ spSuppressMarks. If true, the following flags are treated as false: spRuling, spVRuling, spGrid, 
spTick, and spBaseLine. 

♦ spRuling. If true (the default), horizontal ruling lines are drawn. 

♦ spVRuling. If true, vertical ruling lines are drawn. 

♦ spGrid. If true, grid lines are drawn. 

♦ spTick. If true, tick marks are drawn. 

♦ spBaseLine. If true, and spRuling is also true, the horizontal ruling lines are drawn as a baseline. 

♦ spDataMoveable. If true, then the sPaper's scribble is moveable. 

♦ spDataCopyable. If true, then the sPaper's scribble is copyable. 

tdefine spCapture flagO 

tdefine spProx flag4 

tdefine spFixedPos flag5 

tdefine spPenCoords flag6 

tdefine spGrab flag8 

tdefine spScribbleEdit flagll 



722 PENPOINT API REFERENCE 

Part 5 / Input and Handwriting 



#define 


spRedi splay 


flag7 


tdefine 


spSuppressMarks flagl2 


#define 


spRuling 


flagl 


#define 


spVRuling 


flagl3 


tdefine 


spGrid 


flag9 


#define 


spBaseLine 


flagl4 


tdefine 


spTick 


flagl 


tdefine 


spDataMoveable 


flag2 


tdefine 


spDataCopyable 


flag3 



Messages 



msgNew 

Creates an sPaper object. 

Takes P_SPAPER_NEW, returns STATUS. Category: class message. 



typedef struct SPAPER_NEW ONLY { 



U16 


flags; 


U16 


lineHeight; 


OBJECT 


translator; 


OBJECT 


listener; 


U16 


rows ; 


U16 


cols; 


U16 


charWidth; 


U32 


reserved; 



} SPAPER_NEW_ONLY; 

tdefine sPaperNewFields 
viewNewFields 
SPAPER_NEW_ONLY sPaper; 

typedef struct SPAPER_NEW { 

sPaperNewFields 
} SPAPER NEW, *P SPAPER NEW; 



// Cell height (in points) 

// Translation object 

// This object is made an observer of the 

// sPaper. 

// Rows for shrink wrap layout 

// Cols for shrink wrap layout 

// Cell width (in points) 



msgNewDefaults 

Initializes the NEW structure to default values. 

Takes P_SPAPER_NEW, returns STATUS. Category: class message. 

typedef struct SPAPER_NEW { 

sPaperNewFields 
} SPAPER_NEW, *P_SPAPER_NEW; 

pArgs->win . flags . input 



pArgs->win . flags . style 



= (inputOutProx | input Tip | 
inputStroke | inputlnk | 
inputNoBusy | inputHWTimeout | 
inputAutoTerm | inputTimeout | 
inputHoldTimeout) ; 

|= wsSendGeometry; 



pArgs->view . dataOb ject 


= NULL; 


pArgs->view . createDataOb ject 


= TRUE; 


pArgs->sPaper . flags 


= (spRuling | spRedisplay | 




spScribbleEdit) ; 


pArgs->sPaper . translator 


= NULL; 


pArgs->sPaper . rows 


= 0; 


pArgs->sPaper . cols 


= 0; 


pArgs->sPaper . reserved 


= 0; 


pArgs->sPaper . listener 


= NULL; 
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pArgs->sPaper.lineHeight = 25; // In case read fails, 

read.resld = tagPrLineHeight; 
read. heap = 0; 

read.pData = &pArgs->sPaper.lineHeight; 
read. length = SizeOf(U16); 
ObjCallRet (msgResReadData, theSystemPreferences, &read, s) ; 

// convert line height from hundredths of inches to points. 
pArgs->sPaper.lineHeight = (pArgs->sPaper.lineHeight * 72) / 100; 
pArgs->sPaper.charWidth = pArgs->sPaper.lineHeight; 

msgSPaperGetFlags 

Passes back the sPaper's flags. 
Takes PJJ16, returns STATUS. 
#define msgSPaperGetFlags MakeMsg(clsSPaper, 19) 

msgSPaperSetFlags 

Sets the sPaper's flags. 

Takes PJJ16, returns STATUS. 

#define msgSPaperSetFlags MakeMsg(clsSPaper,20) 

In addition to setting the flags, the scribble self sends msgWinDirtyRect to force itself to redraw with 
the new flags. 

msgSPaperGetTranslator 

Passes back the sPaper's translator object (may be NULL). 

Takes P_OBJECT, returns STATUS. 

#define msgSPaperGetTranslator MakeMsg(clsSPaper,16) 



msgSPaperSetTranslator 

Replaces the sPaper's translator passes back the old translator. 

Takes P_OBJECT, returns STATUS. 

tdefine msgSPaperSetTranslator MakeMsg(clsSPaper,17) 

Important: the old translator is not destroyed. The client is responsible for eventually destroying it. 

In response to this message, the sPaper replaces it translator. (The old translator is passed back.) The 
sPaper adds itself as an observer of the new translator and adds the translator as the translator as an 
observer of the sPaper's scribble (if one exists). 

msgSPaperGetScribble 

Passes back the sPaper scribble object (may be NULL). 
Takes P_OBJECT, returns STATUS. 

♦define msgSPaperGetScribble MakeMsg(clsSPaper, 14) 
Comments See the section "SPaper Components" for more information. 
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msgSPaperSetScribble 

Replaces the sPaper's scribble and passes back the old scribble. 

Takes P_OBJECT, returns STATUS. 

#define msgSPaperSetScribble MakeMsg(clsSPaper, 15) 

Comments Important: the old scribble is not destroyed. The client is responsible for eventually destroying it. 

In response to this message, the sPaper replaces its scribble. (The old scribble is passed back.) The 
sPaper makes its translator (if one exists) an observer of the new scribble. This causes all strokes in the 
new scribble to be sent to the existing translator. 



msgSPaperGetCellMetrics 

Passes back some of sPaper's metrics. 

Takes P_SPAPER_CELL_METRICS, returns STATUS. 

♦define msgSPaperGetCellMetrics MakeMsg(clsSPaper, 11) 

Arguments typedef Struct SPAPER_CELL_METRICS { 

RECT32 cellRect; // centered writing area of the sPaper 

SIZE32 cellSize; // size of an individual cell based on 

// lineHeight and charWidth 
U16 rows; // number of rows displayed 

U16 cols; // number of columns displayed 

} SPAPER_CELL_METRICS, *P_SPAPER_CELL_METRICS; 

Comments In response, sPaper passes back pArgs->cellRect, pArgs->cellSize, pArgs->rows and pArgs->cols. 

Note that pArgs->rows and pArgs->cols are not the values passed to msgNew. (The values passed to 
msgNew are used for shrink wrap layout.) 

See Also msgSPaperGetSizes 



msgSPaperSetCellMetrics 

Sets the sPaper's cell metrics. Resizes and lays out window. 

Takes P_SPAPER_CELL_METRICS, returns STATUS. 

♦define msgSPaperSetCellMetrics MakeMsg(clsSPaper,13) 

Messoge typedef struct SPAPER_CELL_METRICS { 

Arguments RECT32 cellRect; // centered writing area of the sPaper 

SIZE32 cellSize; // size of an individual cell based on 

// lineHeight and charWidth 
U16 rows; // number of rows displayed 

U16 cols; // number of columns displayed 

} SPAPER_CELL_METRICS, *P_SPAPER_CELL_METRICS ; 

Comments In response, sPaper uses the new values of pArgs->cellSize, pArgs->rows and pArgs->cols to compute its 

new window size. It then self sends msgWinLayout to resize and re-layout self. The new value of the 
sPaper's cellRect is passed back in pArgs->cellRect. 



msgSPaperGetSizes 

Passes back the sPaper's line height and character width sizes, in points. 

Takes P_SIZE16, returns STATUS. 

#define msgSPaperGetSizes MakeMsg(clsSPaper,21) 
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Comments The response to this message is similar to the response to msgSPaperGetCellMetrics except that fewer 

values are returned and the values are in points. 

See Also msgSPaperGetCellMetrics 

msgSPaperSetSizes 

Sets the sPaper's line height and character width sizes, in points. 

Takes P_SIZE16, returns STATUS. 

#define msgSPaperSetSizes MakeMsg(clsSPaper,22) 

Comments In response, the sPaper sets its lineHeight and charWidth. It recomputes other sizes that depend on 

those values, and repaints itself if necessary. 

See Also msgSPaperSetCellMetrics 

msgSPaperClear 

Destroys the sPaper's scribble. 
Takes NULL, returns STATUS. 

#define msgSPaperClear MakeMsg(clsSPaper,4) 

Comments In response, the sPaper destroys its scribble, if it has one. 

Stroke Processing Messages 

msgSPaperAddStroke 

Adds a stroke to the sPaper's scribble. 

Takes P_INPUT_EVENT, returns STATUS. 

tdefine msgSPaperAddStroke MakeMsg(clsSPaper,2) 

Comments In response to msgPenStroke, the sPaper self sends this message to add a stroke to its scribble. If the 

sPaper does not have a scribble, one is created. If the sPaper is not capturing input (spCapture flag is 
false), and this is the first stroke added since the last translation, then any existing scribble is destroyed 
and a new one is created. 

The sPaper self sends msgSPaperLocate before adding the stroke to the scribble to allow subclasses to 
process the stroke. 

msgSPaperLocate 

Allows subclasses to process the stroke before it is added to the scribble. 

Takes P_SPAPER_LOCATE, returns STATUS. 

#define msgSPaperLocate MakeMsg(clsSPaper, 6) 

Arguments typedef Struct SPAPER_LOCATE { 

XY32 start; // origin of stroke 

P_UNKNOWN pStroke; // new stroke 

} SPAPER_LOCATE, *P_SPAPER_LOCATE; 

Comments An sPaper's default response to this message is to return stsOK. 

See Also msgSPaperAddStroke 
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msgSPaperDeleteStrokes 

Deletes strokes in the sPaper's scribble that intersect *pArgs. 

Takes P_RECT32, returns STATUS. 

#define msgSPaperDeleteStrokes MakeMsg(clsSPaper, 18) 

In response to this message, the sPaper sends msgScrDeleteStrokeArea to its scribble (after the rectangle 
is converted to the appropriate coordinate system). 

If the spRedisplay flag is true, then sPaper also dirties the specified rectangle in itself to cause repainting 



to occur. 



msgSPaperComplete 

Tells the sPaper that the current stroke is complete. 

Takes nothing, returns STATUS. 

#define msgSPaperComplete MakeMsg(clsSPaper, 3) 

See the 'Typical Scenario" section for a description of why and when this message is sent. 

sPaper responds as follows. If the sPaper has a scribble, it sends msgScrComplete to the scribble. If 
there is no scribble, the sPaper self sends msgSPaperXlateCompleted to "complete" the translation, 
even though the resulting translation will be empty. 

If this message is received while the sPaper is handling msglnputEvent, the status returned from 
msglnputEvent will cause any grab to be released. 

msgSPaperXlateCompleted 



msgSPaperAbort 

Tells the sPaper to abort the entry of the current stroke. 

Takes nothing, returns STATUS. 

#define msgSPaperAbort MakeMsg(clsSPaper, 23) 

imenfs In response to this message, sPaper sends msgSPaperClear to self. 

If this message is received while the sPaper is handling msglnputEvent, the status returned from 
msglnputEvent will cause any grab to be released. 

Data Notification and Retrieval Messages 



msgSPaperXlateCompleted 

Notifies observers that data is available from the sPaper. 

Takes OBJECT, returns STATUS. 

#define msgSPaperXlateCompleted MakeMsg(clsSPaper,128) 

This message has two roles. 

Role 1 : This notification is sent to the sPaper s observers (including the listener) when the sPaper 
decides that translation is complete. Note that the resulting "translation" might be empty. 
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Role 2: sPaper self sends this message when msgSPaperComplete has been received and there is 
nothing to translate. In response to this message, sPaper sends the same message to its observers, as 
described in Role 1 above. 

msgSPaperGetXlateData 

Passes back translated data. 

Takes P_XLATE_DATA, returns STATUS. 

♦define msgSPaperGetXlateData MakeMsg(clsSPaper,7) 

Comments The sPaper's observers typically send this message in response to the sPaper 's msgSPaperCompleted 

notification. See the "Typical Scenario" section for more information. 

If there is no translator, or no scribbles to be translated, the sPaper passes back an empty xlist. 

Otherwise, the sPaper extracts the xlist from its translator. If the sPaper's spPenCoords flag is true, the 
sPaper converts the xlist's coordinates to pen coordinates; otherwise it converts the xlist s coordinates to z 

local window coordinates. Finally, the sPaper passes back the xlist. 

The client must free the passed back xlist. 

See Also msgSPaperGetXlateDataAndStrokes.h.h.h 



msgSPaperGetXlateDataAndStrokes 

Passes back translated data and its associated strokes. 

Takes P_SPAPER_XDATA, returns STATUS. 

Arguments typedef struct SPAPER_XDATA { 

OS_HEAP_ID heap; // In: Heap to allocate space for stroke data 

// (Null means to use osProcessHeapId.) 
P_UNKNOWN pXList; // Out: pointer to xlist 

BOOLEAN toLWC; // In: true to convert strokes to LWC 

// coordinates 
} SPAPER_XDATA, *P_SPAPER_XDATA; 

♦define msgSPaperGetXlateDataAndStrokes MakeMsg(clsSPaper,8) 

Comments The sPaper's observers typically send this message (or msgSPaperGetXlateData) in response to the 

sPaper's msgSPaperCompleted notification. See the "Typical Scenario" section for more information. 

This message is very similar in function to msgSPaperGetXlateData. In fact the first two fields of pArgs 
for this message are the same as the fields of pArgs for msgSPaperGetXlateData 

The only difference between the two messages is that msgSPaperGetXlateDataAndStrokes also passes 
back the stroke information used to produce the translation. The strokes are appended to the xlist as 
elements of type xtStrokel6. 

If pArgs->toLWC is true, then the coordinate information in the strokes is converted to Local Window 
Coordinates (see win.h) before being passed back. 

The client must free the passed back xlist. 

See Also msgSPaperGetXlateData 
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usages Defined by Other Classes 



msgFree 

Defined in clsmgr.h 

Takes P_OBJ_KEY, returns STATUS. 

Comments If the sPaper contains a scribble, it first removes the translator (if it exists) as an observer of the scribble. 

It then sends msgDestroy to the scribble. 

If the sPaper contains a translator, it first remove self as an observer of the translator and then send 
msgDestroy to the translator. 

msgSave 

Defined in clsmgr.h. 

Takes P_OBJ_SAVE, returns STATUS. 

Comments An sPaper responds by sending msgResPutObject to its scribble and translator. (If the scribble and/or 

translator is null, this effectively writes the "null object" id into the resource file.) 

msgRestore 

Defined in clsmgr.h. 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments An sPaper responds by sending msgResGetObject to pArgs->file to restore its scribble and translator 

that were saved while handling msgSave. 

If the restored translator is non-null, the sPaper makes itself an observer of the of the translator. If both 
the translator and scribble are non-null, the sPaper makes the translator an observer of the scribble. 



tnsgSetOwner 

Defined in clsmgr.h. 

Takes P_OBJ_OWNER, returns STATUS. 

Comments In response, an sPaper sends this message to its translator and scribble ( if they are non-null). The 

sPaper then lets its ancestor (clsObject) set the sPaper's ownership. 

msgXlateCompleted 

Defined in xlate.h. 

Takes nothing, returns STATUS. 

Comments An sPaper receives this message because it is observing its translator. The translator uses this message to 

indicate that translation has been complete and that data is available. 

In response to this message the sPaper self sends msgSPaperXlateCompleted, which results in 
msgSPaperXlateCompleted being sent to all the sPaper's observers. 

See Also msgSPaperXlateCompleted 



SPAPER.H 729 

Messages Defined by Other Classes 



msgWInRepaint 

Defined in win.h. 

Takes nothing, returns STATUS. 

Comments An sPaper responds by (1) drawing any necessary grid lines in the window, and (2) if spRedisplay is 

true, sending msgScrRender to its scribble 

msgWinSized 

Defined in win.h. 

Takes P_WIN_METRICS, returns STATUS. 

Comments If the window being resized is self, and a change in height has occurred, and the spFixedPos flag is true, 

then the sPaper's scribble's base is adjusted by the change in height. This causes the scribble to remain at 
a fixed position relative to the upper left corner of the window. As a result of handling this message, 
msgSPaperGetCellMetrics and msgSPaperGetSizes will return different values. 

See Also scribble.h 

msgWinLayoutSelf 

Defined in win.h. 

Takes P_WIN_METRICS, returns STATUS. 

If wsLayoutResize is on in pArgs->options, the sPaper picks a width of 

(cols * cellWidth) + self's borderSize.w 
and a height of 

(rows * lineHeight) + self's borderSize.h 

msglnputEvent 

Defined in input.h. 

Takes P_INPUT_EVENT, returns STATUS. 

Comments sPaper handles msgPenUp, msgPenDown, msgPenStroke and msgPenOutProxUp events. 

An sPaper grabs input by returning stsInputGrabTerminate in response to msgPenDown. 

If flags.spGrab is false, the sPaper relinquishes the grab by returning stsInputTerminate in response to 
msgPenUp. 

If flags.spGrab is true, the sPaper releases the grab by returning stsInputTerminate in response to 
msgPenOutProxUp. msgPenOutProxUp also cause a self send of msgSPaperComplete if flags.spProx is 

set. 

msgPenStroke causes a self send of msgSPaperAddStroke. 

All other msglnputEvent events return stsInputGrablgnored or stslnputlgnored depending on the grab 
state the sPaper is in. 

Return Value stsInputTerminate 

See Also msgSPaperComplete 
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Comments 



msgSelDelete 

Defined in sel.h. 

Takes U32, returns STATUS. 

In response to this message, the sPaper self sends msgSPaperClear. 



msgSelMoveSelection 

Defined in sel.h. 

Takes P_XY32, returns STATUS. 

Comments In response to this message, the sPaper first checks to see if the selection owner can "speak" the 

xferScribbleObject data transfer type. If it cannot, then the sPaper lets its ancestor process the message. 

If it can, and the selection owner is not self, then the sPaper gets the scribble from the selection owner, 
positions it as specified in pArgs, self sends msgSPaperSetScribble, and finally sends msgSelDelete to 
the selection owner. 



msgSelCopySelection 

Defined in sel.h. 

Takes P_XY32, returns STATUS. 

An sPaper s response to this message is identical to its response to msgSelMoveSelection except that the 
sPaper does not send msgSelDelete to the selection owner. 

msgSelMoveSelection 



Comments 



See Also 



Comments 



Comments 



msgSelBeginMove 

Defined in sel.h. 

Takes P_XY32, returns STATUS. 

In response to this message, the sPaper first verifies that it has a scribble and that flags.spDataMoveable 
is true. If either of these fail, the sPaper lets its ancestor process the message. 

Otherwise the sPaper computes the bounding box of the scribble and self sends 
msgEmbeddedWinBeginMove. 

msgSelBeginCopy 

Defined in sel.h. 

Takes P_XY32, returns STATUS. 

In response to this message, the sPaper first verifies that it has a scribble and that flags.spDataCopyable 
is true. If either of these fail, the sPaper lets its ancestor process the message. 

Otherwise the sPaper computes the bounding box of the scribble and self sends 
msgEmbeddedWinBeginCopy. 
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msgXferGet 

Defined in xfer.h. 

Takes P_UNKNOWN, returns STATUS. 

Comments If pArgs->id is xferScribbleObject, the sPaper creates a copy of its scribble and returns the copy in 

pArgs->uid. 

msgXferList 

Defined in xfer.h. 

Takes OBJECT, returns STATUS. 

Comments In response to this message, the sPaper adds the data transfer type xferScribbleObject to the list of data 

transfer types. 

msgTrackProvideMetrics 

Defined in track, h. 

Takes P_TRACK_METRICS, returns STATUS. 

Comments If pArgs->tag is tagMoveCopylconTrack, the sPaper snaps the pen to the center-left of the move/copy 

icon. 
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XGESTURE.H 



Interface file for clsXGesture 
clsXGesture inherits from clsXtract. 

#ifndef XGESTURE_INCLUDED 
#define XGESTURE_INCLUDED 

♦ifndef GO_INCLUDED 

#include <go.h> 

#endif 

tifndef UID_INCLUDED 

♦include <uid.h> 

♦endif 

tifndef GEO_INCLUDED 

♦include <geo.h> 

#endif 



Common #def ines and typedefs 



Gesture Definitions 



These tags define the codes returned for a recognized gesture. Wherever a "gesture id" is called for, one 
of these codes is expected. 

Certain of these gesture codes are OBSOLETE. That is, the shapes that they denote were experimental 
and are no longer recognized by the gesture recognizer. All such obsolete codes are indicated by the 
comment "not generated" at the end of the definition. 



#define xgsNull 
// selection 
#define xgsLeftParens 
♦define xgsRightParens 
#define xgsPlus 
#define xgslTap 
♦define xgs2Tap 
♦define xgs3Tap 
♦define xgs4Tap 

// Removed xgsNTapDrag 
♦define xgsPlusTap 
♦define xgsCheckTap 
♦define xgsTapHold 
♦define xgsPressHold 

// deletion 
♦define xgsCross 
♦define xgsPigtailHorz 
♦define xgsScratchOut 
♦define xgsPigtailVert 



MakeTag (clsXGesture, Oxff) // 255 

MakeTag (clsXGesture, '(') // 40 

MakeTag (clsXGesture, ')') // 41 

MakeTag (clsXGesture, '+') // 43 

MakeTag (clsXGesture, '.') // 46 

MakeTag (clsXGesture, 0x80) // 128 

MakeTag (clsXGesture, 0x81) // 129 

MakeTag (clsXGesture, 0x82) // 130 



MakeTag (clsXGesture, 0x87) 

MakeTag (clsXGesture, 0x88) 

MakeTag (clsXGesture, 0x89) 

MakeTag (clsXGesture, 0x8a) 

MakeTag (clsXGesture, ' X' ) 

MakeTag (clsXGesture, 0x8b) 

MakeTag (clsXGesture, 0x8c) 

MakeTag (clsXGesture, 0x8d) 



// 135 not generated 

// 136 

// 137 

// 138 

// 88 == xgsXGesture 

// 139 not generated 

// 140 

// 141 
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// insert/replace 
♦define xgsCircle 
#define xgsCircleTap 
♦define xgsUpCaret 
♦define xgsRightCaret 
♦define xgsCircleDblTap 
♦define xgsCircleLine 
♦define xgsCircleFlickUp 
♦define xgsCircleFlickDown 
♦define xgsUpCaretDot 
♦define xgsUpCaretDblDot 
♦define xgsDblArrow 
♦define xgsDblCircle 

// move /copy 
♦define xgsUpArrow 
♦define xgsUp2Arrow 
♦define xgsDownArrow 
♦define xgsDown2Arrow 
♦define xgsLeftArrow 
♦define xgsLeft2Arrow- 
♦define xgsRightArrow 
♦define xgsRight2Arrow 

♦define xgsDblUpCaret 

♦define xgsDblDownCaret 

♦define xgsUpTriangle 

♦define xgsDownTriangle 

♦define xgsRightUp 
♦define xgsRightUpFlick 
♦define xgsRightDown 

// white space 
♦define xgsCGesture 
♦define xgsLLCorner 
♦define xgsLLCornerFlick 
♦define xgsLRCorner 
♦define xgsLRCornerFlick 
♦define xgsParagraph 
♦define xgsLeftCaret 
♦define xgsULCorner 

// scroll 

♦define xgsFlickUp 

♦define xgsFlickDown 

♦define xgsFlickLeft 

♦define xgsFlickRight 

♦define xgsDblFlickUp 

♦define xgsDblFlickDown 

♦define xgsDblFlickLeft 

♦define xgsDblFlickRight 

♦define xgsFlickTapUp 

♦define xgsFlickTapDown 

♦define xgsFlickTapLeft 

♦define xgsFlickTapRight 

♦define xgsTrplFlickUp 

♦define xgsTrplFlickDown 

♦define xgsTrplFlickLeft 

♦define xgsTrplFlickRight 

♦define xgsQuadFlickUp 

♦define xgsQuadFlickDown 

♦define xgsQuadFlickLeft 

♦define xgsQuadFlickRight 
// misc 

♦define xgsLineCaretRight 

♦define xgsLineCaretLeft 

♦define xgsLineDblCaret 



MakeTag (clsXGesture 


r '0') 


// 
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sgsOGesture 


MakeTag (clsXGesture 


0x8e) 


// 


142 
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0x8f) 


// 
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MakeTag (clsXGesture 


0x90) 


// 


144 


not 


generated 


MakeTag (clsXGesture 


0x91) 


// 


145 


not 


generated 


MakeTag (clsXGesture 


0x92) 


// 
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MakeTag (clsXGesture 


0x93) 


// 
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0x94) 


// 
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MakeTag (clsXGesture 


0x95) 


// 
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MakeTag (clsXGesture 


0x96) 


// 
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not 


generated 


MakeTag (clsXGesture 


0x97) 


// 


151 


not 


generated 


MakeTag (clsXGesture 


0x98) 


// 
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MakeTag (clsXGesture 


0x99) 


// 
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0x9a) 


// 
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MakeTag (clsXGesture 


0x9b) 


// 
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0x9c) 


// 


156 
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0x9d) 


// 
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MakeTag (clsXGesture 


0x9e) 


// 
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MakeTag (clsXGesture 


0x9f) 


// 
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// 
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// 


161 






MakeTag (clsXGesture 


0xa2) 


// 
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not 


generated 


MakeTag (clsXGesture 


0xa3) 


// 


163 


not 


generated 


MakeTag (clsXGesture 


0xa4) 


// 


164 


not 


generated 


MakeTag (clsXGesture 
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// 


165 






MakeTag (clsXGesture 


0xa6) 


// 


166 
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// 
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MakeTag (clsXGesture 


'C') 


// 
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'L') 


// 
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"DownRight " , "LGesture " 


MakeTag (clsXGesture 


0xa8) 


// 
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"DownRightFlick" 


MakeTag (clsXGesture 


0xa9) 


// 


169 


"DownLeft" 


MakeTag (clsXGesture 


Oxaa) 


// 


170 


"DownLeftFlick" 


MakeTag (clsXGesture 


Oxab) 


// 
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// 
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not 


generated 


MakeTag (clsXGesture 


Oxad) 


// 


173 


"UpRight" 


MakeTag (clsXGesture 


Oxae) 


// 


174 






MakeTag (clsXGesture 


Oxaf) 


// 


175 






MakeTag (clsXGesture 


OxbO) 


// 


176 






MakeTag (clsXGesture 


Oxbl) 


// 


177 






MakeTag (clsXGesture 


0xb2) 


// 


178 






MakeTag (clsXGesture 


0xb3) 


// 


179 






MakeTag (clsXGesture 


0xb4) 


// 


180 






MakeTag (clsXGesture 


0xb5) 


// 


181 






MakeTag (clsXGesture 


0xb6) 


// 


182 


not 


generated 


MakeTag (clsXGesture 


0xb7) 


// 


183 


not 


generated 


MakeTag (clsXGesture 


0xb8) 


// 


184 


not 


generated 


MakeTag (clsXGesture 


0xb9) 


// 


185 


not 


generated 


MakeTag (clsXGesture 


Oxba) 


// 


186 






MakeTag (clsXGesture 


Oxbb) 


// 


187 






MakeTag (clsXGesture 


Oxbc) 


// 


188 






MakeTag (clsXGesture 


Oxbd) 


// 


189 






MakeTag (clsXGesture 


Oxbe) 


// 


190 






MakeTag (clsXGesture 


Oxbf) 


// 


191 






MakeTag (clsXGesture 


OxcO) 


// 


192 






MakeTag (clsXGesture 


Oxcl) 


// 


193 






MakeTag (clsXGesture 


0xc2) 


// 


194 


not 


generated 


MakeTag (clsXGesture 


0xc3) 


// 


195 


not 


generated 


MakeTag (clsXGesture 


0xc4) 


// 


196 


not 


generated 
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// User-defineable 
#define xgsLeftDown 
tdefine xgsLeftUp 
#define xgsUpLeft 

// Undo 

#define xgsVertCounterFlick MakeTag(clsXGesture 

tdefine xgsHorzCounterFlick MakeTag(clsXGesture 



MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 



tdefine xgslnfinity 
#define xgsCircleCrossOut 
// Borders On 
#define xgsBordersOn 

#define xgsAsterisk 

// Capital letters gestures 

tdefine xgsAGesture 

tdefine xgsBGesture 

// for xgsCGesture see above 

tdefine xgsDGesture 

tdefine xgsEGesture 

tdefine xgsFGesture 

tdefine xgsGGesture 

tdefine xgsHGesture 

tdefine xgsIGesture 

tdefine xgsJGesture 

tdefine xgsKGesture 

// for xgsLGesture see xgsLLCorner, above 



MakeTag (clsXGesture 
MakeTag (clsXGesture 

MakeTag (clsXGesture 
MakeTag (clsXGesture 

MakeTag (clsXGesture 
MakeTag (clsXGesture 

MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 



tdefine xgsMGesture 
tdefine xgsNGesture 
tdefine xgsOGesture 
tdefine xgsPGesture 
tdefine xgsQGesture 
tdefine xgsRGesture 
tdefine xgsSGesture 
tdefine xgsTGesture 
tdefine xgsUGesture 
tdefine xgsCheck 
tdefine xgsVGesture 
tdefine xgsWGesture 
tdefine xgsXGesture 
tdefine xgsYGesture 
tdefine xgsZGesture 
tdefine xgsQuestion 



MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 



// graphic gestures in geo.ptc - currently not 
tdefine xgsRect 
tdefine xgsRoundRect 
tdefine xgsSpline 
tdefine xgsPolyline 

tdefine xgsOTapHold 
tdefine xgslTapHold 
tdefine xgs2TapHold 
tdefine xgs3TapHold 
tdefine xgs4TapHold 



0xc5) 
0xc6) 
0xc7) 

0xc8) 
0xc9) 
Oxca) 
Oxcb) 

Oxcc) 



'A' 
'B' 

'D' 
'E' 
'f 

'G' 

'H' 
'I' 
'J' 
'K' 



'M' 

'N' 

'0' 
, p , 

'Q' 
'R' 
'S' 

I ml 

'U' 
'V 
'V 
'W 
'X' 
'Y' 

'Z' 

i ?f 



// 
// 
// 

// 
// 
// 
// 

// 
// 

// 
// 

// 
// 
// 
// 
// 
// 
// 
// 



II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
II 
implemented 



MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 
MakeTag (clsXGesture 

xgsPressHold 
xgsTapHold 
MakeTag (clsXGesture, 
MakeTag (clsXGesture, 
MakeTag (clsXGesture, 



OxfO) 
Oxfl) 
0xf2) 
0xf3) 



Oxf4) 
0xf5) 
Oxf6) 



// 
// 
// 
// 



// 
// 
// 



197 
198 
199 

200 
201 
202 
203 

204 
not 

65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
86 
87 
88 
89 
90 
63 

240 
241 
242 
243 



244 
245 
246 



not generated 



generated 



== xgsCircle 



== xgsVGesture 
== xgsCheck 

== xgsCross 



not generated 
not generated 
not generated 
not generated 



Output Data Structure 



Information returned in an xlist. 

typedef struct XLATE_GDATA { 

U32 gType; // gesture code (one of the 32-bit values defined above) 
XY32 hotPoint; // target point in window coordinates 

} XLATE GDATA, *P XLATE GDATA; 
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Messages 



msgNewDefaults: 

Sets default values in XLATE_NEW structure for a gesture recognizer 

Takes P_XLATE_NEW, returns STATUS. 

Sets 

pArgs->xlate. metrics. charCount = 1; 
pArgs->xlate.metrics.lineCount = 1; 

and all other values to 



msgNew: 

Creates a new Gesture translation object. 
Takes P_XLATE_NEW, returns STATUS. 
ments Note: sets the XLATE_NEW.mode to xlGesture, regardless of the value passed in via pArgs. 

Notification Messages 



msgXGestureComplete: 

Hook for subclasses to postprocess the results of gesture recognition. 
Takes NULL, returns STATUS. 

#define msgXGestureComplete MakeTag(clsXGesture, 64) 

#endif 



Not implemented. 



PENPOINT API REFERENCE / VOL I 
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XLATE.H 



This file contains part of the API definition for clsXtract. For the remainder see xtract.h. 

clsXtract inherits from clsObject. 

Implements basic translation functions for converting pen input, in the form of strokes, to gestures or 
text characters. 

Translators are objects that use pattern recognition techniques to convert pen input to gestures or text 
characters. There are three stages to the translation process: initialization, control (stroke collection and 
recognition), and notification (data output). 

Since the translation object may preprocess input data as it is received, initialization messages should be 
sent before any strokes are added to the object. Initialization messages establish the rules for translation. 

Control messages are used by the client to communicate specific information regarding the state of the 
translation as it pertains to the input stroke stream. 

Notification messages are used by the translation object to notify the client as to the current state of the 
translation process. 

For historical reasons messages and data types relating to translation are defined in terms of two class names: 
clsXlate and clsXtract. Conceptually, clsXlate is an abstract class (a class with no default behavior, i.e. no 
methods) and clsXtract is a subclass of clsXlate which implements methods for a large number of 
messages. As implemented, however, there is no such class as clsXlate in PenPoint 1.0. When PenPoint 
boots, clsXlate is not installed in the class hierarchy, and clsXtract is installed as a subclass of clsObject. 

The clsXtract/ clsXlate does not implement enough behavior to be used directly as a translator. Rather 
translation objects should be created as instances of one of the following subclasses: 

clsXGesture for gestures 

clsXText for letters with minimal language support 

clsXWord for letters as part of normal American English 

clsXTeach for letters when the application is to train therecognition engine. (It is not possible to train 
gestures) 

xtract.h, xgesture.h, xtext.h, xword.h, xteach.h 

#ifndef XLATE_INCLUDED 
♦define XLATE_INCLUDED 

♦ifndef GO_INCLUDED 

♦include <go.h> 

♦endif 

♦ifndef GEO_INCLUDED 

♦include <geo.h> 

tendif 

♦ifndef CLSMGR_INCLUDED 

♦include <clsmgr.h> 

#endif 

♦ifndef XLIST_INCLUDED 

♦include <xlist.h> 

♦endif 

♦ifndef SPELL_INCLUDED 

♦include <spell.h> 

♦endif 
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Common #defines and typedefs 



Internal Constants 



The following are used globally by the translation object. 

♦define xltCharWordTerminator ('\0') // standard string terminator 



♦define xltCharSpace (' ') 

♦define xltCharDotlessI (0x80) 

#define xltCharDotlessJ (0x81) 

♦define xltCharUnknownDefault (0x15) 

♦define xltMaxWordLength (32) 

typedef struct POINT { 

S16 x, y; 
} POINT, * P_POINT; // internal representation of a digitizer point 



// character code for space 
// character code for dotless i (private) 
// character code for dotless j (private) 
// default "meatball" for unrecognized char 
// buffer size for word translations 



Status Values 



The translation object may return the following status values. 



♦define stsXlateBufferOverflow 
♦define stsXlateBadProtoFile 
♦define stsXlateBadTransFile 
♦define stsXlateBadTrigramFile 
♦define stsXlatelnput Truncated 



MakeStatus(clsXlate, 1) 

MakeStatus(clsXlate, 2) 

MakeStatus (clsXlate, 3) 

MakeStatus(clsXlate, 4) 

MakeNonErr (clsXlate, 1) 



Creation Messages 

Characteristics of the insertion pad. 
typedef struct XLATE_METRICS { 



U16 lineCount; 
U16 charCount; 
SIZE 3 2 charBox; 
S32 baselineOffset; 
XY32 origin; 



// number of lines (0 = indeterminate) 

// number of character columns (0 = indeterminate) 

// size of character box (height and width) 

// baseline offset to bottom of char box (if charCount != 0) 

// origin of insertion pad in digitizer coordinates 



} XLATE_METRICS, *P_XLATE_METRICS; 

When "case smarts" are turned on (i.e. xltSmartCaseDisable hwx flag is OFF), the translation object 
will ignore the case in which the user wrote the input and will instead figure out the correct 
capitalization based on the settings in XLATE_CASE_METRICS. XLATE_CASE_TYPE tells the type of 
capitalization rules which the translation string should be made to obey. "No rules" means make 
everything lower case. 

typedef enum XLATE_CASE_TYPE { 

xcmNone, // Don't capitalize anything, force it all to lower case 
xcmSentence,// Capitalize first letter of each sentence, etc 
xcmField // Capitalize as per XLATE_CASE_METRICS . context . field 

} XLATE_CASE_TYPE, * P_XLATE_CASE_TYPE ; 

If the writer is a mixed case writer, then he/she is presumed to write both upper case and lower case 
shapes. An AllCaps Writer, on the other hand, will only write upper case shapes, never lower case shapes. 
This knowledge can help the shape recognizer by limiting the number of alternatives it has to choose 
from. This does not mean, however, that the translation will be all upper case, for it is the job of "case 
smarts" to convert the translation to the correct case. 

typedef enum XLATE_CASE_WRITER { 

xcmMixedCaseWriter, // Writer writes both upper and lower case shapes 

xcmAHCapsWriter, // Writer writes in all upper case shapes 

} XLATE CASE WRITER, * P XLATE CASE WRITER; 
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typedef enum XLATE_CASE_FIELD { 

xcmOnelnitialCapField, // capitalize first letter in the field 

xcmAHInitialCapsField, // capitalize first letter in each 'word' 

xcmAHCapsField, // captialize all letters in the field 
} XLATE_CASE_FIELD, * P_XLATE_CASE_FIELD; 

typedef struct XLATE_CASE_METRICS { 

XLATE_CASE_TYPE type; // type of rule to use 
XLATE_CASE_WRITER writer; // type of input to expect 
union { 

SPELL_CASE_CONTEXT sentence;// specific rules if type is xcmSentence 
XLATE_CASE_FIELD field; // specific rules if type is xcmField 
} context; 
} XLATE_CASE_METRICS, * P_XLATE_CASE_METRICS; 

typedef struct XLATE_NEW_ONLY { 

U32 hwxFlags; // xlate rules (see msgXlateSetFlags) 

U16 charConstraints; // constrained char set flags 

XLATE_METRICS metrics; // insertion pad parameters 

P_UNKNOWN pTemplate; // compiled XTemplate; pNull if none. 

XLATE_CASE_METRICS xlateCaseMetrics; // case post -processing controls. £ 

} XLATE_NEW_ONLY, *P_XLATE_NEW_ONLY; 

typedef struct XLATE_NEW { 

OB JECT_NEW_ONLY ob j ect ; 

XLATE_NEW_ONLY xlate; 
} XLATE_NEW, *P_XLATEJJEW; 

msgNewDefaults: 

Initializes the XLATE_NEW structure to default values. 

Takes P_XLATE_NEW, returns STATUS. Category: class message. 

Messoge typedef Struct XLATE_NEW { 

Arguments OBJECT_NEW_ONLY object; 

XLATE_NEW_ONLY xlate; 

} XLATE_NEW, *P_XLATE_NEW; 

Comments The default values are for everything. 

This message should, of course, be sent to one of the subclasses of clsXtract, not to clsXlate, since 
clsXlate is a fiction, and not to clsXtract, since clsXtract does not implement the complete behavior 
needed to do translation. 



msgNew: 

Creates a new translation object. 

Takes P_XLATE_NEW, returns STATUS. Category: class message. 

Messoge typedef struct XLATE_NEW { 

Arguments OBJECT_NEW_ONLY object; 

XLATE_NEW_ONLY xlate; 

} XLATE_NEW, *P_XLATE_NEW; 

Comments This message should, of course, be sent to one of the subclasses of clsXtract, not to clsXlate, since 

clsXlate is a fiction, and not to clsXtract, since clsXtract does not implement the complete behavior 
needed to do translation. 
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msgFree: 

Destroys a translation object. 
Takes P_NULL, returns STATUS. 
Comments This message should be sent to the object you wish to destroy. 

T Initialization Messages 

The following messages control various settings and modes which govern the way translation is carried 
out. These messages must all be received by the translator BEFORE any strokes are received by it, since 
translators are allowed to begin translating "in the background", (i.e. before the input is complete). 

msgXlateModeSet: 

Sets the mode (i.e. character/code type) of a translation object. 

Takes XLATE_MODE, returns STATUS. 

#define msgXlateModeSet MakeMsg(clsXlate, 5) 

Arguments typedef enum { 

xlCharacter, // obsolete 

xlText, // use default text rules (ASCII) 

xlNumber, // obsolete 

xlGesture, // use default gesture rules 

xlGeometric // obsolete 
} XLATE_MODE, *P_XLATE_MODE; 

Comments The translation object can be configured to processes a variety of character/code types. The mode flag 

determines the type of character set and default behavior for the object. 

msgXlateModeGet: 

Gets the mode of a translation object. 

Takes P_XLATE_MODE, returns STATUS. 

tdefine msgXlateModeGet MakeMsg(clsXlate, 10) 



ssoge 


typedef enum { 




jumenfs 


xlCharacter, 


// obsolete 




xlText, 


// use default text rules (ASCII) 




xlNumber, 


// obsolete 




xlGesture, 


// use default gesture rules 




xlGeometric 


// obsolete 



} XLATE_M0DE, *P_XLATE_M0DE ; 

The mode was set either at msgNew time or by msgXlateModeSet. 

tnsgXlateMetricsSet: 

Tells translator the dimensions and layout of the writing area. 

Takes P_XLATE_METRICS, returns STATUS. 

♦define msgXlateMetricsSet MakeMsg(clsXlate, 8) 

typedef struct XLATE_METRICS { 

U16 lineCount; // number of lines (0 = indeterminate) 

U16 charCount; // number of character columns (0 = indeterminate) 

SIZE32 charBox; // size of character box (height and width) 

S32 baselineOffset; // baseline offset to bottom of char box (if charCount != 0) 

XY32 origin; // origin of insertion pad in digitizer coordinates 

} XLATE METRICS, *P XLATE METRICS; 
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Comments In order to assist the writer and the recognition system, an insertion pad can display guidelines, or 

"character boxes", that direct the writer in targeting. When character boxes are used, the 
XLATE_METRICS are used to communicate the physical box information to the translation object. The 
translator can use this information (when available) to decide how to group the strokes into characters. 

Most internal processes key off the charCount field. If charCount is 0, the translation object assumes 
that there are no boxes. In that case it will default to a heuristic algorithm that combines information 
from the shape matching and context processing to estimate the writing baseline and character spacing. 

(As an aside, the translation object does not use baseline information when charCount is 0. I.e. 
lineCount is ignored in that case.) 

If charCount > 0, the translation object uses lineCount and charCount to calculate the number of boxes 
in the insertion pad. A combination of the charBox height and width and the x and y coordinates of the 
origin are used to define the physical bounds of each box. The translation object then uses this to 
determine character segmentation. 



msgXlateMetricsGet: 

Gets metrics of a translation object. 
Takes P_XLATE_METRICS, returns STATUS. 
#define msgXlateMetricsGet 



Message 
Arguments 



MakeMsg(clsXlate, 16) 



Comments 



typedef struct XLATE_METRICS { 

U16 lineCount; // number of lines (0 = indeterminate) 

U16 charCount; // number of character columns (0 = indeterminate) 

SIZE32 charBox; // size of character box (height and width) 

S32 baselineOffset; // baseline offset to bottom of char box (if charCount != 0) 

XY32 origin; // origin of insertion pad in digitizer coordinates 

} XLATE_METRICS, *P_XLATE_METRICS; 

The metrics were set in response to either msgNew or msgXlateMetricsSet. 



msgXlateStringSet: 

Sets the current textual context for a translation object. 

Takes P_XLATE_STRING, returns STATUS. 

#define msgXlateStringSet MakeMsg(clsXlate, 12) 

Arguments typedef struct XLATE_STRING { 

P_CHAR pCurrentText; // pointer to current text string 
U16 length; // string length 

S16 startlndex; // index of first editable character 

S16 endlndex; // index of last editable character 

} XLATE_STRING, *P_XLATE_STRING; 

Comments The following structure is used to communicate currently displayed text in the insertion pad. It is only 

applicable when using boxed insertion pads. The existing textual information must be registered if the 
translation object is using any string-based knowledge source (such as the dictionary or a template) 
where positional information within the string is crucial for proper recognition. 

It is possible to allow only a portion of the displayed string to be in the insertion pad (and hence, 
editable). To allow for this, startlndex represents the first editable character's position in the string, and 
endlndex represents the last editable characters's position in the string. If the entire string is editable, set 
startlndex = and endlndex = string length. 
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msgXlateSetFlags: 

Sets the translation flags. 
Takes U32, returns STATUS. 

#define msgXlateSetFlags 

// Built-in Rules 

#define xltSegmentVeto flagO 

tdefine xltCaseEnable flag8 

tdefine xltAlphaNumericEnable flag9 

tdefine xltPunctuationEnable flaglO 

tdefine xltVerticalEnable flagl4 

account 

tdefine xltSpaceDisable flagl5 // 

tdefine xltConnectedEnable flagl 

// Knowledge Source Controls 



MakeMsg(clsXlate, 14) 

// allow one and only one char per box 

// prefer standard rules of capitalization 

// prefer standard grouping of letters and digits 

// prefer standard use of punctuation 

// take height and vertical position of chars into 

ignore spaces (translate as one string) 
// currently not implemented 



tdefine xltSpellingEnable 
tdefine xltSpellingVeto 
tdefine xltSpellingPropose 
tdefine xTemplateEnable 
tdefine xTemplateVeto 
tdefine xTemplatePropose 
// Post-processing Rules 
tdefine xltProofEnable 
tdefine xltAbbrEnable 
tdefine xltExpansionEnable 
tdefine xltSmartCaseDisable 
// Not currently implemented 
tdefine hwxGeoPolylines flag24 
tdefine hwxGeoSingleLines flag25 
tdefine hwxGeoLinesAlways flag26 



flag2 



// use dictionary, prefer dictionary words 
flag3 // disallow non-dictionary words 

flag4 // propose from dictionary when stuck 
flag5 // use xTemplate, prefer template words 
flag6 // disallow words not matching template 
flag7 // propose from template when stuck 

flagl 1 // currently not implemented 

flagl2 // currently not implemented 

flagl3 // currently not implemented 

flagl6 // DON'T correct the capitalization 



// currently not implemented 
// currently not implemented 
// currently not implemented 



The translation flags (hwxFlags) govern which of the various scoring rules will be applied in choosing 
the best translation. They include built-in language rules, choice of assisting knowledge sources (speller, 
templates), and postprocessing rules, such as sentence-level case correction. 

Built-in Rules: The translation object can be directed to use various default language rules to assist 
recognition. When a flag is turned on, the translator will show a preference for translations which obey 
the rule associated with that flag. For example if xltCaseEnable is on, the translator will show a 
preference for words that are either all lower case, all upper case or all lower case except the first letter. 

Knowledge Source Controls: The translation object can be directed to use spelling and/or template 
information in order to assist recognition. Each of these knowledge sources, when it is turned on, has a 
choice of four modes of operation: 

Enable, Enable+Veto, Enable+Propose and Enable+Veto+Propose. 

The Enable flag must be ON in all four cases. This enables the use of the knowledge source and causes 
the translator to show a preference for words which conform to the source (i.e. are in the dictionary or 
match the template). If the Veto flag is also on, then the translator will ONLY consider translations 
which conform to the source and will reject all translations which do not. If the Propose flag is also on, 
it allows the translator to change some letters if it will result in a translation which conforms to the 
knowledge source even if the raw shape matcher did not suggest those letters. 

Post-processing Rules: The translation object can apply post-processing rules to assist error-checking 
and proofing (spell correction). The only processing that is currently implemented is the "smart case" 
capability. This capability calls for the translator to use linguistic rules to correct the capitalization of 
the translation. This correction is always applied unless it is disabled by turning the smartCaseDisable 
flag on. 
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msgXlateGetFlags: 

Gets the translation flags of an object. 
Takes PJJ32, returns STATUS. 

tdefine msgXlateGetFlags MakeMsg(clsXlate, 17) 

Comments The translation flags are also called the hwxFlags. 

msgXlateFlagsClear: 

Clears the given set of translation flags. 

Takes U32, returns STATUS. 

#define msgXlateFlagsClear MakeMsg(clsXlate, 15) 

Comments Performs the operation - 

Q. 

hwxFlags &= ~pArgs; — 

thus turning OFF all flags which are ON in pArgs and leaving unchanged those flags which are OFF in 
pArgs. 



msgXlateCharConstrainsSet: 

Sets the character constraints of a translation object. 
Takes P_U16, returns STATUS. 

tdefine msgXlateCharConstraintsSet MakeMsg(clsXlate, 11) 

#define xltDisableUpperCase flagO // disallow A thru Z 

tdefine xltDisableLowerCase flagl // disallow a thru z 

tdefine xltDisableNumerals flag2 // disallow thru 9 

tdefine xltDisableCommonPunct flag3 //disallow .,'!?; :%$#+-* () "=/ 

tdefine xltDisableOtherPunct flag4 // disallow all other punctuation 

Comments Character constraints impose limits on the shapes that the writer is allowed to write. Setting the flag 

when appropriate may improve translation accuracy or performance since the shape matcher will know 
that it does not need to consider certain shapes as possibilities. 

For example, a numeric-only translator can be constructed by setting all of the disable flags except for 
xltDisableNumerals. 

Note that character constraints do not restrict the case of the translation string if "case smarts" are on. 
For example, case smarts may force the translation to be all lower case letters even if the 
xltDisableLowerCase charConstraint flag is set. 

msgXlateCharConstrainsGet: 

Gets the character constraints of a translation object. 
Takes P_U16, returns STATUS. 

tdefine msgXlateCharConstraintsGet MakeMsg(clsXlate, 18) 

Comments The charConstraints were set in response to either msgNew or msgXlateCharConstraintsSet 
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msgXlateTemplateGet: 

Gets the template for a translation object. 
Takes PPJJNKNOWN, returns STATUS. 

♦define msgXlateTemplateGet MakeMsg(clsXlate, 13) 

Comments Will return in *pArgs a pointer to the compiled template currently in effect for the translator. 

msgXlateTemplateSet: 

Sets the template for a translation object. 

Takes PJJNKNOWN, returns STATUS. 

♦define msgXlateTemplateSet MakeMsg(clsXlate, 9) 

Comments The pArg should be a pointer to the "compiled" template created by calling the function 

XTemplateCompile() defined in xtemplt.h 

msgXlateCharMemorySet: 

Sets the current Character memory for character box mode. 

Takes P_CHARACTER_MEMORY, returns STATUS. 

#define msgXlateCharMemorySet MakeMsg(clsXlate, 22) 

Arguments typedef struct CHARACTER_MEMORY { 

U16 position; // position in the string 

P_CHAR usedCharacters; // list of characters already used 

} CHARACTER_MEMORY, *P_CHARACTER_MEMORY; 

Comments In "boxed" mode (which typically is used when editing a short string), the translation object can accept 

a list of characters already attempted in this position. This is used to allow ambiguous character shapes 
to be translated differently on overwrite. 

For example, a writer attempting to enter a lower case "L" may want to avoid repeatedly entering a 
straight vertical stroke and receiving a numeral " 1 " as the translation. The character memory feature 
allows a client that keeps track of previously overwritten text to pass this information to the translation 
object. The translation object will then disallow any character in the "already tried" string. 

This feature is implemented only for single character entries. The Position field refers to the position of 
the character in the XLATE_STRING pCurrentText string. Setting character memory for more than one 
position for a single translation will result in the character memory being ignored in all positions. 



Messoge 
Arguments 



Comments 



msgXlateCharMemoryGet: 

Gets the current Character memory for character box mode. 

Takes P_CHARACTER_MEMORY, returns STATUS. 

tdefine msgXlateCharMemoryGet MakeMsg(clsXlate, 27) 

typedef struct CHARACTER_MEMORY { 

U16 position; // position in the string 

P_CHAR usedCharacters; // list of characters already used 

} CHARACTER_MEMORY, *P_CHARACTER_MEMORY; 

This message is intended for use by subclasses. 
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Message 
Arguments 



Comments 



ftessage 
Arguments 



Comments 



Comments 



msgXlateSetXlateCaseMetrics: 



Sets the "smart case" metrics. 

Takes P_XLATE_CASE_METRICS, returns STATUS. 

tdefine msgXlateSetXlateCaseMetrics MakeMsg(clsXlate, 26) 

typedef struct XLATE CASE METRICS { 



// type of rule to use 

// type of input to expect 



XLATE_CASE_TYPE type; 

XLATE_CASE_WRITER writer; 
union { 

SPELL_CASE_CONTEXT sentence;// specific rules if type is xcmSentence 
XLATE_CASE_FIELD field; // specific rules if type is xcmField 

} context ; 
} XLATE_CASE_METRICS, * P_XLATE_CASE_METRICS; 

The translation object can be directed to use Case (capitalization) heuristics above and beyond the basic 
xltCaseEnable heuristics set in the xlate flags. These rules are communicated via the 
XLATE_CASE_METRICS structure. They are applied in a post-processing pass by the translator, whereas 
the hwxFlags are applied during the initial search for a good translation. 

These rules set expectations for input (writer style) as well as output format. The writer (CASE_WRJTER) 
field prepares the system for the type of input, allowing either mixed case or all upper case input. The 
type (CASE_TYPE) field sets the style of heuristics. The context field sets the specific rules to implement. 

See spell.h for definitions for SPELL_CASE_CONTEXT. 



msgXlateGetXlateCaseMetrics: 

Gets the "smart case" metrics. 

Takes P_XLATE_CASE_METRICS, returns STATUS. 

#define msgXlateGetXlateCaseMetrics MakeMsg(clsXlate, 25) 

typedef struct XLATE CASE METRICS { 



// type of rule to use 

// type of input to expect 



XLATE_CASE_TYPE type; 

XLATE_CASE_WRITER writer; 
union { 

SPELL_CASE_CONTEXT sentence;// specific rules if type is xcmSentence 
XLATE_CASE_FIELD field; // specific rules if type is xcmField 

} context; 
} XLATE_CASE_METRICS, * P_XLATE_CASE_METRICS; 

Returns the values that were set either at msgNew time or by msgXlateSetXlateCaseMetrics. 

msgXlateGetHistoryTemplate: 

Gets the current alternate Translation Template. 

Takes PP_UNKNOWN, returns STATUS. 

tdefine msgXlateGetHistoryTemplate MakeMsg(clsXlate, 23) 

There is no behavior of class xlate associated with the history template other than to respond to the Set 
and Get messages. It may used by the client to implement a "history" or cache mechanism, allowing the 
system to "remember" things previously translated. 
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msgXlateSetHistoryTemplate: 

Sets the current alternate Translation Template. 

Takes P_UNKNOWN, returns STATUS. 

#define msgXlateSetHistoryTemplate MakeMsg(clsXlate, 24) 



p Control Messages 



msgXlateComplete: 

Initiates completion of translation after input is complete. 
Takes NULL, returns STATUS. 

#define msgXlateComplete MakeMsg(clsXlate, 3) 

Comments Obsolete. See msgXtractComplete in xtract.h. 

Not to be confused with msgXlateCompleted (see below). 

Other control messages are defined in xtract.h. In general, the client does not need to play an active role 
in sending or receiving control messages. 



Notification Messages 



msgXlateData: 

Allows a client to read the results from a translation object. 

Takes P_XLATE_DATA, returns STATUS. 

#define msgXlateData MakeMsg(clsXlate, 2) 

Arguments typedef struct XLATE_DATA { 

OS_HEAP_ID heap; // In: heap to allocate structures 

struct XLIST *pXList; // Out: pointer to return info 
} XLATE_DATA, *P_XLATE_DATA; 
typedef struct XLATE_BDATA { // 

RECT32 box; // bounding information 

S32 baseline; // baseline offset 

} XLATE_BDATA, *P_XLATE_BDATA; 

typedef struct WORD_ENTRY { // structure for a word 

SI 6 score; // confidence factor 

CHAR string [xltMaxWordLength] ; // word 
} WORD_ENTRY, *P_WORD_ENTRY; 

typedef struct WORD_LIST { // structure for a list of words 

RECT32 bound; // bounding information 

U16 count; // number of words in list 

WORD_ENTRY word[l]; // variable length array of words 

} WORD_LIST, *P_WORD_LIST; 

Comments The client reads the translation results from the translation object via this message. 

The translation object fills in the clients xlist data with the output data. The specific xlist type is 
dependent upon the specific translation class. Please refer to xlist.h for the information on each 
translation class. 
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The output data is only available upon completion of the translation process. Partial data cannot be read 
before the client has received the completion notification message (msgXlateCompleted) from the 
translation object (see below). 

The output data is a read-once function. That is, you cannot send msgXlateData twice to the same 
translator. All translation object internal resources pertaining to the translated data are freed during the 
reading process. 

This message must be sent to an instance of one of the subclasses of clsXtract, such as clsXText or 
clsXGesture. The clsXtract itself does not implement any behavior for this message. 

msgXlateCompleted: 

Notification to client that the translation has been completed. 

Takes OBJECT, returns STATUS. 

tdefine msgXlateCompleted MakeMsg(clsXlate, 128) 

Comments This notification is sent by the translation object to its observers to inform them that translation is 

completed. Upon receiving this message the client should send msgXlateData (see above) back to the 
translator to read the output. 

The pArgs is the id of the translator. 
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XLFILTER.H 



See Also 



Function Protot% 



This file contains the API definition for some of the xlist filters, xlist filters provide a mechanism to alter 
the contents of an xlist. 

Xlists are a dynamic list of dynamic items. Their API is defined in the file xlist.h. This file simply defines 
a filter function to operate on the xlist. This function should have probably been included in the file 
xlist.h. 

xlist.h 

#ifndef XLFILTER_INCLUDED 
#define XLFILTER_INCLUDED 

#ifndef XLIST_INCLUDED 
#include <xlist.h> 
#endif 



XList2Text 

Converts a translator xlist to lines of xtText & xtBounds. 

Returns STATUS. 

STATUS EXPORTED XList2Text ( 
P_XLIST pXList) ; 

Converts xlist of the form: 

[xtBounds xtTextWord [xtTextWord]] xtTextListEnd 

into: 

[xtBounds xtText] 

where xtText is the space delimited xtTextWords. 

Sets the xl£XList2Text flag in the xlist to indicate that the filter has been executed on this list. A 
subsequent invocation of XList2Text with this flag set will return stsOK without processing any data. 
Turning this flag off will cause another pass over the data. This will have no side affects. 

xlist.h 
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This file contains the API definition for xlist. Xlists provide a set of dynamic list routines used by 
translators. 

The functions described in this file are contained in XLIST.LIB. 

An xlist is a set of routines for manipulating a list of items of data type P_XLIST_ELEMENT. These items 
are allocated from a heap passed into the xlist when it is created. Elements have some flag settings, a data 
type, and a pointer. The pointer points to data defined by the data type, whose allocation is dependent 
on the flag settings. 

Elements in the list are indexed from to entries- 1. A series of functions are provide to create and 
destroy lists, traverse lists, access and set list elements, insert new elements, and delete elements. 

In addition, functions are provided to "filter" data from the xlist. These filters either extract useful data 
from the xlist in the form of a data structure, or actually "mutates" the xlist into an xlist of a different 
format. These filters are defined in this file and in xlfilter.h. 

Xlists of various types are used throughout the system. Primarily, they are used to pass translation 
information between the hwx system and the client. See xlate.h for example uses in the hwx engine; and 
gwin.h, spaper.h, or insert.h for example uses inside the UI toolkit. 

Typical users create xlists (XListNew), add and delete items (XListlnsert, XListDelete), access the value 
of items (via filters or XListGet), traverse (XListTraverse) and free them (XListFree). Other functions, 
while useful, are rarely used. 

Xlists have associated with them a heap with which use to allocate the memory needed to store the 

elements (P_XLIST ELEMENT). They can also use this heap to allocate space for the data pointer field of 

an element, when the corresponding elements flag setting is xfHeapAlloc. In this situation, the element 
data pointer will be freed when the xlist is freed, or when XListFreeData is called. Allocating other 
memory off the xlist heap, although not recommended, is possible. It would be the clients responsibility 
to free this data. However, typically the user of an xlist will allocate space for the data pointer off of the 
heap using XListAlloc, insert an element into the xlist with the data, and allow the xlist to manage and 
free the memory. 

#ifndef XLIST_INCLUDED 
#define XLIST_INCLUDED 

#ifndef GO_INCLUDED 
#include <go.h> 
#endif 

#ifndef OSHEAP_INCLUDED 

tinclude <osheap.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

♦include <clsmgr.h> 

#endif 

#ifndef GEO_INCLUDED 

tinclude <geo.h> 

#endif 
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Common #defines and typedefs 

Xlist Data Structure 

A pointer to an xlist is a pointer to a private data structure. This pointer is passed to the xlist function to 
create, destroy, and manipulate xlists. 
typedef P_UNKNOWN P_XLIST; 

Xlist Flags 

These flags are stored in the xlist. They are useful to store xlist specific data. flagO through flag 15 are 
reserved for GO internal use, while flag 16 through flag31 is for client use. The only flag currently used 
indicates that XList2Text has been run on the xlist. This optimizes successive calls to this xlist filter, 
allowing it to return without running the filter. Running the filter a second time, because the flag is 
clear, is harmless. 

♦define xflXList2Text flagO 

Element Types 

These are the data types for elements of an xlist. An element contains a type, a data pointer and flags. 
For each data type, the data pointer varies. 



Enuml6(XTYPE) { 








xtNull, 


// pData 


= 


null = 


xtBounds , 


// pData 


= 


P BDATA (clsXGesture, clsXText) 


xt Gesture, 


// pData 


= 


P GDATA (clsXGesture) 


xtText, 


// pData 


= 


P_STRING (clsXText, XList2Text) 


xt Object, 


// pData 


= 


OBJECT 


xtBoundsX, 


// pData 


= 


P BDATA (screen relative) 


xtCharAttrs, 


// pData 


= 


P XLIST CHAR ATTRS (txtxlist.h) 


xtParaAttrs, 


// pData 


= 


P XLIST PARA ATTRS (txtxlist.h) 


xtTabs, 


// pData 


= 


P XLIST TABS (txtxlist.h) 


xtCharPos, 


// pData 


= 


TEXT INDEX 


xtText Li st, 


// pData 


= 


P_WORD_LIST (hwx) 


xt Spare 1, 


// pData 


= 




xtSpare2, 


// pData 


= 




xtSpare3, 


// pData 


= 




xt Spare 4, 


// pData 


= 




xt Geometric, 


// pData 


= 


P XGEO DATA unused 


xtTextListEnd, 


// pData 


= 


NULL (sPaper) 


xtText Word, 


// pData 


= 


P XTEXT WORD (xtext) (clsXtext, 


xtStrokel6, 


// pData 


= 


P_SPAPER_STROKE_DATA (spaper) 


xt Space, 


// pData 


= 


U32 unused 


xtTeachData, 


// pData 


= 


P_XTEACH_DATA (xteach) 


xtUID, 


// pData 


= 


UID of the gesture object 


xtEmbedObject, 


// pData 


= 


P_TEXT_EMBED_OBJECT (txtdata.h) 


xtExtended, 


// pData 


= 


UID, client data 


xtLastEntry 


// last entry in the xtList 



sPaper) 



}; 



Xlist Element 



This data structure defines an element in an xlist. An xlist element contains some flags, a data type, and 
a pointer to some data. The allocation and type of data depend on both the flags and the data type of 
the element. 

typedef struct XLIST_ELEMENT { 

U16 flags; // Element flags. Mostly allocation information. 

XTYPE type; // Type of data in pData 

P_UNKNOWN pData; // Pointer to data of element 

} XLIST ELEMENT, *P XLIST ELEMENT; 
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fy Element Flags 

These flags are stored in the XLIST_ELEMENT flags, and indicate information about the elements. They 
can be changed dynamically simply by accessing the xlist element. Other flags not used are reserved for 
future use. 

P^ Allocation flags 

These flags indicate how to treat memory for the element. They indicate how the element will be freed 
when the xlist is freed, and how to allocate space for the element when duplicated via XListDup (cannot 
duplicate xfObject). Setting more than one of these flags will have unpredictable results, as these are 
mutually exclusive flags. 

tdefine xfHeapAlloc flagO // Allocated from the xlist heap 

♦define xfObject flagl // Element is an object. Cannot duplicate 

tdefine xfXList flagl4 // Element is a P_XLIST 

This flag indicates that the elements data is used elsewhere, and should not be freed when freeing the 
xlist. It will be the clients responsibility to free the data if he sets this flag. 

#define xfExtracted flagl5 // Set if the data is used elsewhere 

P^ Traversal function 

This callback function is used to as a function template called on elements of the xlist when traversing 
the xlist. See XListTraverse for more details. This function takes an xlist, an xlist element, and a user 
defined data pointer. 

Function Prototype typedef STATUS FunctionPtr (P_XPROC) ( 
P_XLIST pXlist, 
P_XLIST_ELEMENT pElement, 
P UNKNOWN pUserData) ; 



Public Functions 



XListNew 

Creates a new xlist. 

Returns STATUS. 

Function Prototype STATUS PASCAL XListNew ( 

OS_HEAP_ID heap, // In: heap to allocate the xlist 

P_XLIST *ppXList); // Out: Pointer to the P_XLIST 

Comments Creates and allocates an xlist from the specified heap, using the heap to allocate space for the 

P_XLIST_ELEMENT entries in the list, and for XListAlloc. 

XListFree 

Frees an xlist and all its data. 
Returns STATUS. 

Function Prototype STATUS PASCAL XListFree ( 

P_XLIST pXList); // In: xlist to free 

Comments Traverses the xlist elements and frees the data (unless the element has xfExtracted set). For each element, 

frees the memory appropriately by traversing the xlist with function XListFreeData. 

See Also XListFreeData 
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XListGetFlags 

Passes back the XList flags for the xlist. 

Returns STATUS. 

function Prototype STATUS PASCAL XListGetFlags ( 

P_XLIST pXList, // In: xlist to get the flags from 

P_U32 pFlags); // Out: pointer to the flags 

Comments flagO through flagl5 are reserved for GO internal use. flagl6 through flag31 are for client use. 



XListSetFlags 

Sets the XList Flags. 

Returns STATUS. 

Function Prototype STATUS PASCAL XListSetFlags ( 

P_XLIST pXList, // In: xlist to set the flags from 

U32 flags); //In: new flags to set 

Comments Sets the flags associated with the xlist. flagO through flagl5 are reserved for GO internal use. flagl6 

through flag3 1 are for client use. 



XListMetrics 

Passes back the number of entries and heap Id. 

Returns STATUS. 

Arguments typedef struct XLIST_METRICS { 

OS_HEAP_ID heap; 
U16 entries; 
} XLIST_METRICS, *P_XLIST_METRICS; 

Function Prototype STATUS PASCAL XListMetrics ( 

P_XLIST pXList, // In: xlist to get the metrics from 

P_XLIST_METRICS pMetrics) ; // Out: metrics of the xlist 

Comments Passes back the number of entries in the xlist, and the heap used to allocate xlist memory. Note that 

there is no corresponding set' metrics function, as dynamically changing the heap or count would have 
drastic side affects. 



XListlnsert 

Creates a new element at the index'th location. 

Returns STATUS. 

STATUS PASCAL XListlnsert ( 

P_XLIST pXList, // In: xlist to insert item into 

U16 index, // In: index of location to insert at 

P_XLIST_ELEMENT pElem) ; // In: element to insert 

Allocates space for and creates a P_XLIST_ELEMENT in the xlist at the specified location. If index >= 
entries, the element is appended to the end of the list. The element data pointer allocation and storage 
depends on the type of the element. The following example shows a client inserting a 7 character string 
into an xlist. The element type is xtText and the insertion at the beginning of the xlist: 

XLIST_ELEMENT elem; 
elem.type = xtText; 
elem. flags = xfHeapAlloc; 
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XListAlloc(pXList, 7, Selem.pData) ; 
strcpy (elem.pData, "String"); 
XList Insert (pXList, 0, &elem) ; 



XListDelete 

Delete the element at the index'th location. 
Returns STATUS. 



Function Prototype STATUS PASCAL XListDelete ( 

P_XLIST pXList, // In: 

U16 index); // In: 



xlist to delete item from 
index of item to delete 



Comments 



See Also 



Delete the element at the specified location. This calls XListFreeData to free any memory taken by the 
element data pointer. Frees memory associated with storing the P_XLIST_ELEMENT in the xlist. 

XListFreeData 



XListTraverse 

Iterates across the list of elements. 

Returns STATUS. 

STATUS PASCAL XListTraverse ( 

P_XLIST pXList, // In: xlist to traverse 

P_XPR0C pProc, // In: call back function to call for each element 

PJJNKNOWN pUserData) ; // In/Out: User defined data pointer 

Iterates across the elements in the xlist. A callback function (pProc) is handed to this function, and is 
called for each element passing in the element and a client pointer as defined in P_XPROC. If any call to 
pProc returns anything but stsOK, the traversal is terminated and the status code returned. Nested 
traversals are allowed and supported. 

XListlndex 



Function Prototype 



Comments 



See Also 



Function Prototype 



Comments 



XListlndex 

Passes back the current traversal index. 
Returns STATUS. 



STATUS PASCAL XListlndex ( 
P_XLIST pXList, 
P_U16 plndex) ; 



// In: pointer to xlist 
// Out: current index 



See Also 



Passes back the index for the current traversal. If no traversal is taking place, returns 0. Note that if 
nested traversals are taking place, the index of the current traversal will be returned. Once the 
sub-traversal is completed, the parent traversals index is restored and returned appropriately via calls to 
XListlndex. 

XListTraverse 



Function Prototype 



XListSet 

Stores the copy of the index'th element. 
Returns STATUS. 



STATUS PASCAL XListSet ( 

P_XLIST pXList, // In: 

U16 index, // In: 

P_XLIST_ELEMENT pPtr) ; //In: 



xlist pointer 

index of element 

new element to store at location 
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Comments Stores the passed in element as the element in the specified location. If index is > number of entries, will 

store in the last item in the list. Care should be taken, as the old item stored in that location is not freed 
and is the clients responsibility. Useful only if changing an entire item in the xlist. Rarely used. 

XListGet 

Passes back a copy of the index'th element. 
Returns STATUS. 

Function Prototype STATUS PASCAL XListGet ( 

P_XLIST pXList, // In: xlist pointer 

U16 index, // In: index of element 

P_XLIST_ELEMENT pPtr) ; // Out: Copy of element data. 

Comments Passes back a copy of the index'th element. The element, data type, and data pointer will be copied. 

Hence the data pointer is a direct pointer to the data. 



XListGetPtr 

Passes back a pointer to the index'th element. 

Returns STATUS. 

Function Prototype STATUS PASCAL XListGetPtr ( 
P_XLIST pXList, 
U16 index, 
P_XLIST_ELEMENT *ppPtr) ; 

Comments Passes back a pointer to the index'th element in the xlist. Extreme care should be taken when accessing 

this pointer, as it is the pointer stored in the xlist. Useful only if the client wishes to change some 
information about an existing item in the xlist. Rarely used. Note that the data pointer field is the same 
returned by XListGet. 

See Also XListGet 

XListAlloc 

Allocate some memory from the XList heap. 

Returns STATUS. 

Function Prototype STATUS PASCAL XListAlloc ( 

P_XLIST pXList, // In: xlist pointer 

SIZEOF size, // In: size of the requested allocation 

P_UNKNOWN pMem) ; // Out: pointer to the allocated memory 

Comments Allocates memory off of the xlist heap. Typically used to allocate space for the data pointer of an element 

that has xfHeapAlloc set. Space for such an element data pointer will be freed in XListFreeData, called 
when the xlist is freed via XListFree, or when the item is deleted via XListDelete. Other memory can be 
allocated using this function, although it is the clients responsibility to ensure that it is freed. 

See Also XListFreeData 



XListFreeData 

Releases the data with the given entry. 
Returns STATUS. 
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Function Prototype 



Comments 



See Abo 



STATUS PASCAL XListFreeData( 

P_XLIST pXList, // In: xlist pointer 

P_XLIST_ELEMENT pElem, //In: element to free 

P_UNKNOWN pUserData) ; // In: User defined data structure 

Frees data associated with the passed in element. Returns stsOK if xfExtracted is set on the element. 
Frees the memory appropriately if xfHeapAlloc is set. Sends msgFree to the object if xfObject is set. 
Calls XListFree if xfXList is set. Called from XListFree for each element in the xlist, and called from 
XListDelete when an item is deleted from the xlist. 

XListFree 



Function Prototype 
Comments 

See Also 

Return Volue 



XListDup 

Duplicates the contents of one xlist into another. 
Returns STATUS. 



STATUS PASCAL XListDup ( 
P_XLIST pSrcXList, 
P_XLIST pDestXList) ; 



// In: source xlist 

// In/Out: destination xlist 



Traverses the source xlist and calls XListDupElement for each item in the source xlist with the 
destination xlist. If XListDupElement returns a non-stsOK return code for an element in the xlist, the 
xlist to the point of the return code is copied and the duplication terminated at that point. 

XListDupElement 

stsBadParam the xlist duplication terminated before completion 



XListDupElement 

Duplicate the source element, append to the destination. 

Returns STATUS. 

STATUS PASCAL XListDupElement ( 
P_XLIST pXList, 
P_XLIST_ELEMENT pElem, 
P_XLIST pDestXList); 

Duplicates the element and appends it to the end of the destination xlist. When the element is 
xfHeapAlloc, allocates space for the element from the destination xlist heap, and memcpy's the contents. 
When the element is xfXList, creates a new xlist using the passed in xlist's heap, and duplicates all 
elements in the xlist. Any other element data type (xfObject) is not copy-able and will return 
stsBadParam. 

stsBadParam The element type could not be duplicated. 

XListDup 



Function Prototype 



Comments 



Return Value 
See Also 



r Xlist Filters 



XList2Gesture 

Extracts the gestural information from an xlist. 
Returns STATUS. 
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Argwments typedef struct X2GESTURE { 

U32 msg; // gesture type 

RECT32 bounds; // gesture bounding box 

XY32 hotPoint; // gesture hot point 

} X2GESTURE, *P_X2GESTURE; 

fyricfion Prototype STATUS PASCAL XList2Gesture ( 

P_XLIST pXList, // In: xlist to run filter on 

P_X2GESTURE pData) ; // Out: converted data structure 

Comments Given an xlist containing xtBounds followed by xtGesture, (the xlist typically returned by the 

clsXGesture translator after completed translation), this function extracts the useful information and 
stores in a standard c data structure. This function is used internally in gWin to convert the gesture 
translator data structure into a more useful form. 



gwin 



,h.h.h 



XList2StringLength 

Passes back the length of the string that XList2String will need. 

Returns STATUS. 

Function Prototype STATUS PASCAL XList2StringLength ( 
P_XLIST pXList, 
P_U16 pLength); 

Comments Computes the necessary length of a string that XList2String will need to copy a string. Includes space for 

the terminating null character. 

XList2String 

Extracts the text information from an xlist. 

Returns STATUS. 

Arguments typedef Struct X2STRING { 

U16 count; // In: buffer size 

P_CHAR pString; // In: pointer to the buffer 

} X2 STRING, *P_X2 STRING; 

Function Prototype STATUS PASCAL XList2String( 

P_XLIST pXList, // In: xlist to process 

P_X2STRING pData) ; // In: X2String data structure pointer 

Comments Converts an xtBounds/xtText xlist into a string. Clips the returned string at the passed in count. This 

string includes a null terminating character. The function takes an xlist of the form: 

[xtBounds [xtText]] 

and converts it into a string. As an example, suppose the xlist contains: 

xtBounds 1 xtText 1 xtText2 xtText3 xtBounds2 xtText4 xtText5. 

This is converted into: 

xtText lxtText2xtText3\nxtText4xtText5 

More typically, this function called on an xlist that has had adjacent xtText entries merged by 
XList2Text. Typical usage is during processing of an xlist returned from msgXlateGetData. Here the 
client simply wants to know the string returned, so he will call XList2Text, XList2StringLength (unless 
he knows how big the string will be), and XList2String to get the string. 

See Also XList2Text.h 
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JF Debugging Functions 



XListDump 

Debugging interface for displaying an xlist in the debug log. 

Returns STATUS. 

STATUS EXPORTED XListDump ( 

P_XLIST pXList) ; // In: array header 

When called on an xlist, traverses the elements and displays useful information about the xlist in the 
debug log. It displays this information by calling a display routine that is dependent on the type of the 
element. A display routine can be registered for an element type using XListDumpSetup. If no display 
routine has been provided for an element type, it will display the generic information for the element 
consisting of the type, the flags, and the element data pointer. 

XListDumpSetup 



Function Prototype 



Comments 



See Also 



XListDumpSetup 

Sets the xlist debug log display routine by type. 

Returns STATUS. 

STATUS EXPORTED XListDumpSetup ( 

XTYPE type, // In: xtype to bind this procedure to 

P_XPROC pProc, // In: function to be called when dumping 

U32 data); // In: type specific data passed to pProc in traversal 

Called to register display routines for xlist element types with the xlist. This display routine will be called 
when the particular element type traversed when calling XListDump. 

XListDump 



Fonction Prototype 



Comments 
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XSHAPE.H 



This file contains the API for clsXShape, a skeletal class designed to be subclassed by particular shape 
recognition engines. In particular, the GO Write shape recognizer, clsCTShape, is a subclass of 
clsXShape. 

clsXShape inherits from clsOpenServiceObject. 

tifndef XSHAPE_INCLUDED 
♦define XSHAPE_INCLUDED 

♦ifndef GO_INCLUDED 

♦include <go.h> 

#endif 

♦ifndef CLSMGR_INCLUDED 

♦include <clsmgr.h> 

#endif 

♦ifndef OSHEAP_INCLUDED 

♦include <osheap.h> 

♦endif 

♦ifndef OPENSERV_INCLUDED 

♦include <openserv.h> 

♦endif 



Terminology change 



// NEW NAME (use these) 
♦define theShapeEngines 
♦define thelnstalledShapeProfiles 
♦define clsShapeEngineService 
♦define clsShapeProfilelnstallMgr 
♦define msgShapeSvcCurrentChanged 
♦define SHAPE_SVC_CURRENT_CHANGED 
♦define P SHAPE SVC CURRENT CHANGED 



OLD NAME (avoid using these, from uid.h) 

theHWXEngines 

thelnstalledHWXProtos 

clsHWXEngineService 

clsHWXProtoInstallMgr 

msgHWXSvcCurrentChanged 

HWX_SVC_CURRENT_CHANGED 

P HWX SVC CURRENT CHANGED 



Common #defines and typedefs 



♦define xsMaxCharList 20 // largest allowable matchArraySize for msgXShapeRecognize 
♦define xsMaxPath 4 // most strokes allowable to send to msgXShapeRecognize 

♦define xsMinMatchScore minS16 // worst possible score for translation 
♦define xsDigitizerResolution 254 // temporary hack. Eventually variable 

The basic types of shape profile ("resource") data stored in files. This refers to the "alphabet" which the 
resource is able to recognize, not the use to which the recognized value will be put. In particular a text 
resource may be used as part of the process of recognizing gestures, since some gestures are upper case 
letters. 



Enuml6 (XS_RESOURCE_TYPE) 
xsResText = 0, 

xsResReserved = 1, 
xsResGesture = 2 

}; 



// alphabetic (ascii) 

// reserved for use by GO 

// gestures 
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The types of data structure used to return information from msgXShapeRecognize. 

Enuml6(XS_MATCH_TYPE) { 

xsMatchAscii =1, // uses XS_ASCII_MATCH data structure 

xsMatchGesture = 2, // uses XS_GESTURE_MATCH data structure 

xsMatchlnternal = 3, // uses subclass-specific data structure 

xsMatchInternal2 = 4, // uses alternate subclass-specific data structure 

}; 

Eight principal compass directions for straight lines. 

Enuml6(XS_DIRECTI0N) { 

xsRight = 0, 

xsUpRight = 1, 

xsUp = 2, 

xsUpLeft = 3, 

xsLeft = 4, 

xsDownLeft = 5, 

xsDown = 6, 

xsDownRight = 7, 

// Special indicators 

xsAHDirections = 8, // used internally 

xsDirEndMark =9 // marks end of array of directions 

}; 

#define xsNumDirections (8) 
#define XSNextDirectionCCW(d) (((d) + 1) & 7) 
#define XSNextDirectionCW(d) (((d) - 1) & 7) 
#define XSOppositeDirection(d) ((d) A 4) 

tdefine XSDeltaDirect ion (start, end) (((end) - (start)) & 7) 
#define XSDeltaDirectionAdd( start, delta) (((start) + (delta)) & 7) 

The following structures capture basic information about strokes (a stroke being a sequence of points 
passed through by the pen). See msgXShapeStrokePreview for further details. 

typedef struct XS_OCTAGON { 

S16 limit [xsNumDirections] ; // max projection in each direction 
} XS_OCTAGON, * P_XS_OCTAGON; 

Data structure for returning information about recognition of an ascii character from 
msgXShapeRecognize. 

typedef struct XS_ASCII_MATCH { 

S16 score; // "penalty" for the match 

U8 character; // ascii code of proposed translation 

U8 segmentOffset;// reserved for GO. msgXShapeRecognize should set to 

} XS_ASCII_MATCH, *P_XS_ASCII_MATCH; 

Data structure for returning information about recognition of a gesture from msgXShapeRecognize. 

typedef struct XS_GESTURE_MATCH { 

SI 6 score; // "penalty" for the match 

U32 gestureld; // proposed translation (id codes defined in xgesture.h) 

POINT hotPoint; // coordinates of target point of the gesture 

} XS_GESTURE_MATCH, *P_XS_GESTURE_MATCH; 

Data structure for returning information about recognition of a straight line or a dot. Used by the GO 
context level processing to aid in segmentation. These scores are calculated by the GO context engine; 
they should not be calculated or used by 3rd party shape engine developers. 

typedef struct XS_LD_MATCH { 

S16 dotScore; // Score for a dot. 

S16 lineScore02; // Score for horiz/vert line 

S16 lineScorel3; // Score for forw/backw slanted line 
} XS LD MATCH, *P XS LD MATCH; 
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Initialization Messages 

The XS_STROKE record holds information pertinent to a single stroke. PenPoint computes all fields of 
this structure except pData and numData. The latter two are (optionally) computed by the shape 
matching engine. They are intended to hold whatever information the shape matcher wishes to extract 
from a single individual stroke. 

typedef struct XS_STROKE { 

struct XS_STROKE *pNextStroke;// pointer to next stroke 

struct XS_STROKE *pPrevStroke;// pointer to previous stroke 

U16 strokeld; // a unique identifier of this stroke 

struct POINT *pPoint; // arr of digitizer points (pendown to penup) 

U16 numPoints; // number of digitizer points (excl. end marker) 

XS_OCTAGON bound; // bounds of this stroke 

P_UNKNOWN pData; // subclass-specific data extracted from stroke 

U16 numData; // subclass-specific counter for pData 

XS_ASCII_MATCH 

asciiMatch[xsMaxCharList] ;// cached results of single stroke recog. 

XS_LD_MATCH ldMatch; // scores for line and dot matches 

} XSSTROKE, *P_XS STROKE; 5 

Q. 

z 

JF Initialization Messages 

msgNewDefaults: 

Initializes the. XSHAPE_NEW structure to default values. 

Takes P_XSHAPE_NEW, returns STATUS. Category: class message. 

Comments Zeros out pArgs->xshape and sets 

pArgs->xshape.resType = xsResText; 

pArgs->xshape . resolution = xsDigitizerResolution; 



msgNew: 

Creates a new shape matching object. 

Takes P_XSHAPE_NEW, returns STATUS. Category: class message. 

Arguments typedef struct XSHAPE_NEW_ONLY { 

P_UNKNOWN pProfile; // ptr to data in subclass specific format 
U16 numProfile; // how many records (e.g. if pProfile pts to array) 
XS_RESOURCE_TYPE resType; // type of profile: xsResText, resGesture 
OBJECT profDirHandle; // handle to directory where profile resides 
S16 resolution; // digitizer granularity (dots per inch) 
S16 charConstraints; // flags to set restricted character sets 
SI 6 reservedl6; // pad for now 
U32 reserved[9]; // may be used in future 
} XSHAPE_NEW_ONLY, *P_XSHAPE_NEW_ONLY; 

typedef struct XSHAPE_NEW { 

openServiceObjectNewFields \ 

XSHAPE_NEW_ONLY xshape; 
} XSHAPE_NEW, *P_XSHAPE_NEW; 

Comments This message is sent to the xshape subclass by the service manager when someone has requested a new 

shape matching engine. The service manager has filled in all of the xshape fields. In responding to this 
message it is merely necessary to copy the fields of xshape_new data into the new object's private 
instance data. 
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msgFree: 

Destroys the object, releasing any memory associated with the translation. 

Takes pNull, returns STATUS. 

ments If any heaps were created in response to msgNew, this is the time to destroy them. NOTE: This is 

NOT the place to free memory occupied by the data pointed to by pProfile. That memory was allocated 
by your service class in response to msgXShapeSvcCurrentChanged and should only be free in response 
to the next occurrence of the same message. 

Control Messages 



msgXShapeStrokePreview: 

Computes and stores data relating to a single stroke 

Takes P_XSHAPE_STROKE_PREVIEW, returns STATUS. 

tdefine msgXShapeStrokePreview MakeMsg(clsXShape, 3) 

Arguments typedef struct XSHAPE_STROKE_PREVIEW { 

P_XS_STROKE pFirst Stroke; // IN: pointer to stroke record 

} XSHAPE_STROKE_PREVIEW, *P_XSHAPE_STROKE_PREVIEW; 

Comments This msg gives the class the opportunity to extract and store information that applies to an individual 

stroke, not to the combined set of strokes that form a character. (The latter extraction should occur 
entirely within the method for msgXShapeRecognize.) 

This message is sent by the input system as part of its background processing of strokes as they are 
entered by the user. Background processing allows the system to produce the final translation more 
quickly after the user taps the translate button. 

Furthermore, a single stroke may be submitted more than once to the shape engine for recognition, as 
the context engine tries out different combinations of strokes searching for the best segmentation. Thus 
the stroke will be "previewed" only once, but may appear in several different combinations of strokes 
submitted for recognition. 

The subclass is responsible for defining the format and managing the memory that contains the 
information extracted in the preview process. The pointer pData in the XS_STROKE record should be set 
to point to this data. The field numData of the XS_STROKE record is available to record the number of 
records pointed to by pData (if it's an array). 

Memory for *pData should be allocated from a local heap whose heapld has been stored in the instance 
data for the object. The heap should be created in response to msgNew and destroyed in response to 
msgFree. 

The method for msgXShapeStrokePreview may assume that the following fields of the XS_STROKE 
record have already been calculated: 

strokeld 

bound 
pPoint 
numPoints 

All other fields should be ignored. 
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Control Messages 

The strokeld uniquely identifies the stroke (as far as this object is concerned). 

The bound implicitly defines the bounding octagon for the stroke by recording for each of the 8 
directions the maximum of the projections of all points in the stroke in that direction. Given a point P 
and a direction d, the projection of P in direction d is defined to be the x-coordinate of P in a 
coordinate system which is rotated d*45 degrees counterclockwise from the base coordinate system. 
Computationally this works out to: 



X 


if d==0 


(xsRight) 


( x+y)/r 


if d==l 


(xsUpRight) 


y 


if d==2 


(xsUp) 


(-x+y)/r 


if d==3 


(xsUpLeft) 


-x 


if d==4 


(xsLeft) 


(-x-y)/r 


if d==5 


(xsDownLeft) 


-y 


if d==6 


(xsDown) 


( x-y)/r 


if d==7 


(xsDownRight) 



where r is sqrt(2). Division by r is simulated in integer arithmetic as multiplication by 5 followed by 
(integer) division by 7. 

From the bound the method can calculate other quantities as needed using the following formulas: 

baseline = - bound. limit [xsDown] ; 

// because -max{-y} = min{y} 

height = bound. limit [xsUp] + bound. limit [xsDown] ; 

// because max{y} + max{-y} = max{y} - min{y} 

width = bound. limit [xsRight] + bound. limit [xsLeft] ; 

// because max{x} + max{-x} = max{x} - min{x} 

pPoints points to an array of digitizer points, terminated with a record with coordinates (minSl6, 
minS16). numPoints tells how many points are in the array, EXCLUDING the terminating record. (So 
numPoints can also be taken as the index of the terminating record.) The Oth record corresponds to 
penDown, the (numPoints- l)th record to penUp. 

msgXShapeRecognize: 

Provide possible translations for a set of strokes. 

Takes P_XSHAPE_RECOGNIZE, returns STATUS. 

#define msgXShapeRecognize MakeMsg(clsXShape, 5) 

Arguments typedef struct XSHAPE_RECOGNIZE { 

P_XS_STROKE pFirstStroke;// IN: linked list of (at most xsMaxPath) strokes 
XS_MATCH_TYPE matchType; // IN: type of record in output array (matchAscii 

// for XS_ASCII_MATCH, xsMatchGesture for XS_GESTURE_MATCH) 
U16 matchArraySize; // IN: number of records in output array (at 

// most xsMaxCharList) 

P_UNKN0WN pMatchResults;// IN: ptr to output array 
} XSHAPE_RECOGNIZE, *P_XSHAPE_RECOGNIZE; 

Comments The set of strokes (given as a linked list) is a combination which the context level is testing to see if it 

represents a single character or gesture. The job of the shape engine is to return an array of the most 
likely translations (or "matches") together with a weight (or "score") for each of them. If the strokes do 
not match any of the forms which the shape engine is designed to recognize, it should return an empty 
array (i.e. the first record should be marked with score xsMinMatchScore). 

Scores are or negative, with representing the best possible match. Scores below represent 
progressively worse matches. The range is open ended below, but generally the scores for the most 
unlikely but still remotely possible translations should fall in the -80 to -120 range, or very occasionally 
below -120. 
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Different recognition technologies may have radically different approaches for arriving at scores and 
correspondingly different models of what the scores mean. One technology may assign scores as a 
measure of the amount of deviation from an ideal form, a kind of Euclidean distance function. Another 
technology may arrive at scores through a process of statistical tests, so the score would represent the 
amount of statistical evidence there is against a particular translation. Yet another technology may 
compute probabilities. 

In order to deal uniformly with a variety of different shape recognition technologies, the context level 
processor requires that the scores reported by the shape engine be scaled or calibrated according to the 
following guidelines: 

1. "Reasonable" scores should fall roughly in the range to -100. 

2. "SCORES SHOULD BE SCALED LOGARITHMICALLY," with every 10 point drop in score 
representing roughly a 50% reduction in confidence/probability/proximity etc. Thus for example a 
translation with a score of -50 is 1/8 as "good" (or 1/8 as "likely" or 8 times as "far" from being perfect) 
as a translation with a score of -20. 

3. The score for each translation should reflect the confidence in that translation only. It should NOT 
be influenced by the confidence in any other translation. In particular, a high score for one translation 
does not preclude a high score for another translation. For example 'o' and 'O' may both score high 
(even perfect). In this way, scores need not behave like probabilities: they do not represent slices from a 
fixed pie. 

4. Similarly, there is no requirement that the scores "add up" to a fixed total. For a particular sample, all 
of the scores may be poor, or the recognizer may even send back no translations. The context engine is 
depending on this fact in order to be able to use the shape engine to help it choose the correct character 
segmentation. 

5. Scores should not be "tainted" by knowledge of character frequency in English or any other linguistic 
considerations. It is the job of the context level processing to take linguistic information into account. 
The shape engine must consider all characters as a priori equally likely, otherwise the bias for common 
characters in text will be duplicated at both levels, resulting in unwanted effects. 



msgXShapeShapeCompatible: 

Checks the possibility of translating the strokes as the char 

Takes P_XSHAPE_COMPATIBLE, returns STATUS. 

tdefine msgXShapeShapeCompatible MakeMsg(clsXShape, 6) 

Arguments typedef struct XSHAPE_COMPATIBLE { 

P_XS_STROKE pFirstStroke;// IN: linked list of strokes 
U8 character; // IN: desired translation for the strokes 

U8 strokeCount; // IN: how many strokes in the linked list 

BOOLEAN compatible; // OUT: is translation a priori possible 

} XSHAPE_COMPATIBLE, *P_XSHAPE_COMPATIBLE; 

Comments Sees if there is anything about the strokes that absolutely rules out the letter as a translation. For 

example, some shape matchers may rule out certain translations based on the number of strokes in 
the list. 

This message is sent by the context level only when it has been instructed to allow the dictionary 
(spelling) or a template to propose characters when the shape level is stuck. The context level makes this 
check just be sure that there is some remote possibility that the strokes do represent the proposed 
character before allowing the dictionary or template to propose it. 
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Training Messages 



msgXShapeShapeEvaluate: 

Checks how well the shape matcher translates the character. 

Takes P_XTEACH_DATA, returns STATUS. 

tdefine msgXShapeShapeEvaluate MakeMsg(clsXShape, 7) 

Comments Reports back how well the current engine translates the strokes, knowing what the correct translation is. 

Does NOT cause the engine to learn the new shape if it is translated poorly. 

msgXShapeShapeLearn: 

Forces shape matcher to learn new shape. 

Takes P_XTEACH_DATA, returns STATUS. 2 

z 



tdefine msgXShapeShapeLearn MakeMsg(clsXShape, 8) 

Usually invoked based on the results from msgXShapeShapeEvaluate. 



PENPOINT API REFERENCE / VOL I 
PART S / INPUT AND HANDWRITING 



XTEACH.H 



Interface file for clsXTeach 
clsXTeach inherits from clsXtract. 

tifndef XTEACH_INCLUDED 

#define XTEACH_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

#ifndef UID_INCLUDED 

#include <uid.h> 

#endif 

#ifndef GEO_INCLUDED 

tinclude <geo.h> 

tendif 



Common #defines and typedefs 



typedef enum { 

// evaluation results 
xteachNoMatch, 
xteachSingular, 
xteachSuperior, 
xteachEquivalent , 

xt eachSecondary , 

xteachlnferior, 



xteachNotProposed, 
xteachMisRecognized, 
xteachEvaluateFailed, 
// execute results 
xteachOK, 

xteachGeometricUpdated, 
xteachPrototypeAdded, 
xteachOutOfMem, 
xteachPrototypeRemoved, 
xteachPrototypeDowngraded, 
xteachAbort, 
xteachExecuteFailed 
} TEACHJ3TATUS, *P_TEACH_STATUS ; 

#define xteachMaxConflict (64) 
tdefine xteachMaxCharConflict (8) 
typedef struct XTEACH_DATA { 

U32 id; 

TEACH_STATUS status; 

U16 conflictCount; 

CHAR conflicts [xteachMaxConflict] ; 

U32 conflict Id [8]; 

S16 conflictPenalty; 

P_UNKNOWN pFirst Stroke; 

P_UNKNOWN pContext; 

XY32 target; 

CHAR hotPointPath; 

CHAR hotPointExtrema; 
} XTEACH DATA, * P_XTEACH_DATA; 



//no matches 

// matches only the correct character 

// matches the correct character best 

// matches the correct character and an 

// incorrect character equally well 

// matches an incorrect character best, 

// but also matches the correct character 

// same as secondary, except that the best 

// match is marginal 

// matches only incorrect characters marginally 

// matches an incorrect character with a good score 



// character/ symbol id 

// evaluation results 

// number of conflicting protos 

// conflicting characters 
// indices of conflicting protos 
// penalty to assess 
// pointer to first stroke 
// pointer to HWX context 
// coordinate of hot point target 
// 

// 
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Messages 



rgwment 



msgNewDefaults: 

Sets default values for a new Teach translation object. 
Takes P_XLATE_NEW, returns STATUS.. 



msgNew: 

Creates a new Teach translation object. 
Takes P_XLATE_NEW, returns STATUS.. 



msgXlateData: 

Returns Teach results. 

Takes P_XLATE_DATA, returns STATUS.. 

typedef struct TEACH_DATA { 

TEACHJ3TATUS status; // required action 

CHAR charConflicts [xteachMaxCharConflict] ; // conflicting characters 

} TEACH DATA, *P TEACH DATA; 



msgXTeachSetld: 

Establishes expected translation results. 
Takes P_CHAR, returns STATUS. 
fdefine msgXTeachSetld 



MakeMsg(clsXTeach, 0x01) 



msgXTeachExecute: 

Executes teaching per TEACH_STATUS. 
Takes P_XLIST, returns STATUS. 
fdefine msgXTeachExecute 



MakeMsg(clsXTeach, 0x02) 



msgXTeachEvaluationGet: 

Reads evaluation data. 

Takes P_XLATE_DATA, returns STATUS. 

fdefine msgXTeachEvaluationGet 



MakeMsg(clsXTeach, 0x03) 



msgXTeachSetTarget: 

Sets the target coordinates for the hot point. 
Takes P_XY32, returns STATUS. 
fdefine msgXTeachSetTarget 



MakeMsg(clsXTeach, 0x05) 
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Notification Messages 



f Notification Messages 



msgXTeachCompleted: 

Signals completion of training. 

Takes P_XLIST, returns STATUS. 

tdefine msgXTeachCompleted MakeMsg(clsXTeach, 0x04) 

Comments This message is sent to all observers of the translation object following successful completion of the 

method for msgXTeachExecute. 
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XTEMPLT.H 



Translation Template Specifications for input fields 

#ifndef XTEMPLT_INCLUDED 
#define XTEMPLT_INCLUDED 

/DS0010 Compilation: print ASCII input and hex-address of result. 
/DS0020 Choices: print Hex address and ASCII list of choices plus count. 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

tifndef OS_INCLUDED 

#include <os.h> 

#endif 

#ifndef XLATE_INCLUDED 
tinclude <xlate.h> 
#endif 

f Definitions 

maxXTemplateXlateChoices is the number of different symbols thatbe in a CharList template. 
maxXtmPictureLength is the longest atemplate may be. 



tdefine maxXTemplateXlateChoices 
#define maxXtmPictureLength 



128 // Alphabet Size 

128 // Picture string length limit 



Common Typedefs 



Jjr Template Types 



Templates are used to constrain handwritten input in order totranslation accuracy. For example, if a field 
can onlydigits, constraining the input for that field to only digitsthat the letters 'O', T, and 'Z', are 
never seen for the'O', '1', and '2'. There are several different ways toinput, each of which 
corresponds to a different template 



Enuml6 (XTEMPLATE_TYPE) 
xtmTypeNone , 
xtmTypeGesture , 
xtmType Shape, 
xtmTypeCharList , 
xtmTypeWordList, 
xtmTypeP i ct ure , 
xtmTypeRegEx, 
xtmTypeTrie, 

}; 



{ 



// no constraints 

// limited to known gestures 

// limited to known shapes (NOT IMPLEMENTED) 

// limited to a set of characters 

// limited to a set of words 

// described by a picture language 

// described by a regular expresssion (NOT IMPLEMENTED) 

// precompiled 
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PJr Template Modes 

A template may be interpreted in a variety of special modes. In general,modes describe circumstances 
under which incomplete input will bethe same as complete input. 

Enuml6(XTEMPLATE_M0DE) { 

xtmModeDefault =0, //No special modes 

xtmModePrefixOK = flagO, // input matching a prefix of the template is 

// considered to match the template. 
xtmModeLoopBackOK = flagl, // the template is considered to repeat over 

// and over 
xtmModeCoerced = flag2, // Input should be coerced to match the 

// template, even if it doesn't match exactly 

// Only meaningful for xtmTypeWordList templates. 
}; 

^ Template Header 

Every template is a single allocated block of memory containing nopointers. The template header 
contains information abouttemplate, including what's needed to file a template. 

typedef struct XTEMPLATE_TRIE_HEADER { 

U16 xtmTrieLength; 

U16 xtmTrieRevision; 

XTEMPLATE_TYPE xtmTrieType; 

XTEMPLATE_MODE xtmTrieMode; 
} XTEMPLATE_TRIE_HEADER, * P_XTEMPLATE_TRIE_HEADER, 

* * PP_XTEMPLATE_TRIE_HEADER; 

fy Template Metrics Structure 

This structure is returned via the XTemplateGetMetrics subroutine, below. The major uses of this 

structure are to get ato the template header in order to get the template length socan be filed, and to 
get access to the original template string. 

typedef struct XTEMPLATE_METRICS { 

P_XTEMPLATE_TRIE_HEADER pXtmHeader; // Template len, rev, etc. 

P_CHAR pXtmString; // Original string, NULL for word 

// list or gesture 

P_UNKNOWN pXtmTrieBase; // Base of compressed TRIE structure 

U16 xtmTrieBaseLen; // Size of the compressed region 
} XTEMPLATE_METRICS, * P_XTEMPLATE_METRICS; 

Functions 

XTemplateCompile 

Given a type and an ASCII template representation, build a template structure. 

Returns STATUS. 

Argymenfs typedef struct XTM_ARGS { 

XTEMPLATEJTYPE xtmType; // What kind of template? 

XTEMPLATEJMODE xtmMode; // What special modes? 

P_UNKNOWN pXtmData; // ascii template 

} XTM_ARGS, *P_XTM_ARGS; 

Function Prototype STATUS EXPORTED XTemplateCompile ( 

P_XTM_ARGS pXtmArgs, // Xtemplate Arguments 

OS_HEAP_ID heap, // heap to use 

PP_UNKNOWN ppXtmDigested // Out: compiled template 

); 
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Functions 

The currently implemented types have the following meanings: 

xtmTypeNone pXtmData is unused. This is the same as having no template at all. 

xtmTypeGesture pXtmData points to an XTEMPLATE_GESTURE_LIST. 

xtmTypeCharList pXtmData contains a list of valid characters. 

xtmTypeWordList pXtmData contains a list of all the different words that are legal in this field. This 
should be a PP_STRING pointing to a list of pointers to the words. Each word is a normal 
null-terminated string and the pointer list must be terminated with a Nil(P_STRING). 

xtmTypePicture pXtmData contains a list of all the picture strings that are valid in this field. A picture 
string contains any of the following characters: 

9: input must be a digit (0-9) 
a: input must be alphabetic 

A: input must be upper-case alphabetic a 

n: input must be alphanumeric z 

N: input must be upper-case alphanumeric 
x: input may be anything 

[: introduces a list of characters, Unix-style, [abc] is a single character position which must 
contain 'a', 'b', or 'c'. [a-m] matches any letter 'a through 'm'. [a\-m] matches any of 'a, '-', or 'm'. 
\: literal escape. Input must match next 
character. (Only needed to escape the above 
special characters). 

For example, a modern California licence plate 
looks like this: 

#AAA### 

To include older forms of California plates, we 
might use: 

#AAA### 
###AAA 
AAA### 

either \n or tab separated. N.B. Multiple 
picture strings will not be supported in the 
first release. 

A Social Security Number (with mandatory- 
hyphens) would be coded like this: 

Pictures currently can't be used for variable 
length data. 

This special structure is used for xtmTypeGesture templates. 

typedef struct XTEMPLATE_GESTURE_LIST { 

U32 count; // number of gestures in the list 

P_MESSAGE pGestures; // pointer to array of allowed gestures 
} XTEMPLATE_GESTURE_LIST, * P_XTEMPLATE_GESTURE_LIST; 

Space is allocated as required. 
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Basic Xtemplate Arguments 



XTemplateGetMetrics 

Given a pointer to a translation template, extract various salient facts about it and return them. 

Returns STATUS. 

Function Prototype STATUS EXPORTED XTemplateGetMetrics ( 

P_UNKNOWN pXTemplate, // Template to extract the metrics of 
P_XTEMPLATE_METRICS pXtmMetrics // Out: metrics of the template 

) ; 

Can fail if the template version is too far out of date. 

XTemplateSetMode 

Change the mode in an already-created XTemplate. 
Returns STATUS. 

Function Prototype STATUS EXPORTED XTemplateSetMode ( 

P_UNKNOWN pXTemplate, // Compressed Template 

XTEMPLATE_MODE xtmMode // New mode 

); 
Changing xtmPreflxOK or xtmLoopBackOK may have no effect. 

XTemplateFree 

Free an existing Template. 
Returns STATUS. 

Function Prototype STATUS EXPORTED XTemplateFree ( 

P_UNKNOWN pXtmDigested // compiled template ptr. 

); 
Checks for pNull and just returns stsOK 



XTemplateWordListSort 

Given a pointer to a list of pointers to strings, sort the list of pointers so the strings appear in 
alphabatical order. 

Returns void. 

void EXPORTED XTemplateWordListSort ( 

PP_CHAR ppStringBase // compiled template 
); 
Last pointer in list must be Nil(P_STRING) 

XTemplateCheckWord 

Check if a word is in a template. 
Returns BOOLEAN. 

Function Prototype BOOLEAN EXPORTED XTemplateCheckWord ( 

P_UNKNOWN pXtmData, // compiled template 

P_CHAR pWord // Word to check 

); 
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Functions 



XTemplateCheckGesture 

Check if a gesture is in a template. 

Returns BOOLEAN. 

rtion Prototype BOOLEAN EXPORTED XTemplateCheckGesture ( 

P_UNKNOWN pXtmData, // compiled template 
MESSAGE gesture // gesture to test 

); 

XTemplateAddWord 

Add a word to a wordlist template. 
Returns STATUS. 



STATUS EXPORTED XTemplateAddWord ( 

PPJJNKNOWN ppXtmData, 

P_CHAR pWord, 

OS_HEAP_ID heap // heap to use 

); 



PP_UNKNOWN ppXtmData, // In/Out: compiled template o. 

P_CHAR pWord, // Word to add Z 



XTemplateDeleteWord 

Delete a word from a wordlist template. 
Returns STATUS. 

STATUS EXPORTED XTemplateDeleteWord ( 

PP_UNKNOWN ppXtmData, // In/Out: compiled template 

P_CHAR pWord, // Word to add 

OS_HEAP_ID heap // heap to use 

); 

XTempltlnit 

DLL Initialization routine. 

Returns STATUS. 

STATUS EXPORTED XTempltlnit (void) ; 

Included for compatibility; not to be called by developers. 
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XTEXT.H 



Defines the API for clsXText 
clsXText inherits from clsXtract. 

#ifndef XTEXT_INCLUDED 

♦define XTEXT_INCLUDED 

#ifndef GO_INCLUDED 

tinclude <go.h> 

tendif 

#ifndef UID_INCLUDED 

# include <uid.h> 

tendif 

tifndef XLATE_INCLUDED 

tinclude <xlate.h> 

tendif 



Common #defines and typedefs 



typedef struct XTEXT_WORD { 
RECT32 bounds; 
CHAR Str[l]; 

} XTEXT WORD, *P XTEXT WORD; 



// xt Text Word data 

// bounding box 

// text string, terminated 



Messages 



msgNewDefaults: 

Fills in default values to XLATE_NEW structure. 

Takes P_XLATE_NEW, returns STATUS.. 

All fields are set to except the following hwxFlags which are turned ON: 

alphaNumericEnable 

punctuationEnable 

verticalEnable 

caseEnable 

In most cases 

smartCaseDisable 

is also on (i.e. there will be NO "smart case" postprocessing to correct the capitalization of letters). The 
exception is that if the writer is an all caps writer (as determined by the global preference setting) then 
the default setting is OFF (i.e. there WILL be smart case postprocessing). 
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msgNew: 

Creates a new Text translation object. 
Takes P_XLATE_NEW, returns STATUS. 

msgXTextGetXList: 

Convert data to XList. 

Takes P_XLATE_DATA, returns STATUS. 

#define msgXTextGetXList MakeMsg(clsXText, 0x01) 

msgXTextWordList: 

subclass opportunity to alter word list/disambig Called during the disambiguation extraction pass. 

Takes P_WORD_LIST, returns STATUS. 

#define msgXTextWordList MakeMsg(clsXText, 0x02) 

msgXTextComplete: 

Hook for subclasses to postprocess translation results from clsXText 

Takes P_XLIST, returns STATUS. 

#define msgXTextComplete MakeMsg (clsXText, 0x81) 

clsXtext responds to msgXlateComplete by completing the translation and then self-sending this 
message (msgXTextComplete) to allow its subclasses to post-process the translation results. 

msgXTextNewLine: 

Indicates the start of a new line to subclasses. 

Takes P_UNKNOWN, returns STATUS. 

#define msgXTextNewLine MakeMsg (clsXText, 0x82) 



msgXTextModLine: 

Indicates a modification of a line to subclasses. 

Takes P_UNKNOWN, returns STATUS. 

#define msgXTextModLine MakeMsg (clsXText, 0x83) 
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XTRACT.H 



This file contains part of the API definition for clsXtract. For the remainder see xlate.h. 
clsXtract inherits from clsObject. 

#ifndef XTRACT_INCLUDED 
tdefine XTRACT_INCLUDED 
#ifndef GO_INCLUDED 
#include <go.h> 
#endif 

tifndef CLSMGR_INCLUDED 
#include <clsmgr.h> 
#endif 



Messages 



msgSave: 

Saves an extraction object. 

Takes P_OBJ_SAVE, returns STATUS. 

Writes the instance data for this object out to a file. 

msgRestore: 

Restores an extraction object. 
Takes P_OBJ_RESTORE, returns STATUS. 
ments Reads back in from a file the instance data for an extraction object and recreates the object. 

Initialization Messages 

msgAdded: 

Attachment to a scribble object 
Takes OBJECT, returns STATUS. 



«©m«ie«fs 



The extraction object receives this message when it has been made an observer of a scribble object. 
When it receives this message, the extractor queries the scribble for all strokes which have been added to 
the scribble up to this time. Henceforth the scribble object will send msgScrAddedStroke to the 
extraction object every time a new stroke is added to the scribble. Thus one way or another the extractor 
has access to all the strokes associated with the scribble. 

An extractor cannot be an observer of more than one scribble object at a time. 
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msgRemoved: 

Detachment from a scribble object 

Takes OBJECT, returns STATUS. 

The extraction object receives this message when it is no longer an observer of the scribble object. 

msgXtractGetScribble: 

Reads the id of the attached scribble object. 

Takes P_OBJECT, returns STATUS.. 

#define msgXtractGetScribble MakeMsg(clsXtract, 1) 

This message is used to obtain the id of the scribble object that this extraction object is attached to. It 
can be used by the client or by a subclass if it is interested in modifying and/or reading the scribble 
information directly. 



Control Messages 



msgScrAddedStroke: 

Add a stroke to the extraction object. 

Takes P_SCR_ADDED_STROKE, returns STATUS. 

This message is received by the extractor from the scribble object each time a new stroke is added to the 
scribble. 

msgScrRemovedStroke: 

Remove a stroke from the extraction object. 

Takes P_SCR_REMOVED_STROKE, returns STATUS. 

This message is received by the extractor from the scribble object each time an existing stroke is deleted 
from the scribble. 

msgXtractStrokesClear: 

Clears out all strokes previously sent to translation object by scribble 

Takes NULL, returns STATUS. 

tdefine msgXtractStrokesClear MakeMsg(clsXtract, 3) 

Effectively restarts the translator as if it had just been attached to a fresh scribble. 

As a side effect, the shape engine is released. A new shape engine will be attached as soon as new strokes 
get added by the scribble. 

All the settings of the translator remain unchanged (e.g. hwxFlags, xlateCaseMetrics, xlateMetrics, etc). 

This message was formerly called msgXtractContextClear. The new name more accurately reflects its 
functionality. 
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Control Messages 



msgScrCompleted: 

Notification that no more strokes will be added to scribble. 

Takes NULL, returns STATUS. 

This message is sent by the scribble object to the extraction object when the scribble has determined that 
no more strokes will be added. When it receives this message, the extractor will self-send the message 
msgXtractComplete (see below) to kick off the final stages of translation. 



msgXtractComplete: 

Hook for subclasses to complete the translation. 

Takes NULL, returns STATUS. 

#define msgXtractComplete MakeMsg(clsXtract, 0x81) 

Comments The extraction object self-sends this message when it receives the message msgScrCompleted. This 

message will be processed by the appropriate subclass of clsXtract which will complete the translation. 

Note that in certain instances (such as multiple line text pads), the translation object may have already 
translated a subset of the existing strokes as they were entered. This message tells the translation object 
to finish up (complete) the translation and not wait for any further strokes. 
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XWORD.H 



This file contains the API definition for clsXWord. 
clsXWord inherits from clsXText. 

#ifndef XWORD_INCLUDED 
tdefine XWORD_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

#ifndef UID_INCLUDED 

#include <uid.h> 

#endif 



Common #defines and typedels 



#define xWordSpellCorrection 
tdefine xWordSpellOnly 
tdefine xWordProofEnable 
#define xWordAbbrEnable 



flagO 
flagl 
flag2 
flag3 



Messages 



msgNewDefaults: 

Fills in default values for a new Word translation object. 

Takes P_XLATE_NEW, returns STATUS.. 

The default values are the same as for clsXText, except for the following hwxFlag setting 

xltSpellingEnable will be ON 

xltSmartCaseDisable will be OFF 

In addition, 

pArgs->xlate.xlateCaseMetrics.type = xcmSentence; 
pArgs->xlate.xlateCaseMetrics. writer = xcmMixedCaseWriter; 

Capitalize first letter of each sentence, etc. 



msgNew: 

creates a new Word translation object. 
Takes P_XLATE_NEW, returns STATUS. 



msgXWordComplete: 

Hook for subclasses to indicate completion. 

Takes NULL, returns STATUS. 

#define msgXWordComplete MakeMsg (clsXWord, 0x81) 

Not implemented 
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XSHAPE_NEW_ONLY, API 1:763 
XSHAPE_RECOGNIZE, API 1:765 
XSHAPE_STROKE_PREVIEW, API 1:764 
XSNextDirectionCCW, API 1:762 
XSNextDirectionCW, API 1:762 
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XTEACH_DATA, API 1:769 
XTEMPLATE_GESTURE_LIST, API 1:775 
XTEMPLATE_METRICS, API 1:774 
XTEMPLATE_MODE, API 1:774 
XTEMPLATE_TRIE_HEADER, API 1:774 
XTEMPLATEJTYPE, API 1:773 
XTemplateAddWord, API 1:777 
XTemplateCheckGesture, API 1:777 
XTemplateCheckWord, API 1:776 
XTemplateCompile, API 1:774 
XTemplateDeleteWord, API 1:777 
XTemplateFree, API 1:776 
XTemplateGetMetrics, API 1:776 
XTemplateSetMode, API 1:776 
XTemplateWordListSort, API 1:776 
XTempltlnit, API 1:777 
XTEXT.WORD, API 1:779 
XTM_ARGS, API 1:774 
XTYPE, API 1:752 
XY1 6, API 1:233 
XYl6ToPenStroke, API 1:7 10 
XY32, API 1:233 
XY32inRect32, API 1:236 
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Your comments on our software documentation are important to us. Is this manual 
useful to you? Does it meet your needs? If not, how can we make it better? Is there 
something we're doing right and you want to see more of? 

Make a copy of this form and let us know how you feel. You can also send us marked 
up pages. Along with your comments, please specify the name of the book and the page 
numbers of any specific comments. 

Please indicate your previous programming experience: 

□ MS-DOS □ Mainframe □ Minicomputer 

□ Macintosh □ None □ Other 



How useful was this book? 

Was information easy to find? 

Was the organization clear? 

Was the book technically accurate? 

Were topics covered in enough detail? 

Additional comments: 
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Your name and address: 

Name 



Company 
Address _ 
City 



State 



Zip 



Mail this form to: 



Team Manager, Developer Documentation 
GO Corporation 
919 E. Hillsdale Blvd., Suite 400 
Foster City, CA 94404-2128 

Or fax it to: (4 15) 345-9833 
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PenPoint™ Application Programmatic Interface , Volume I 

Together with Volume II, PenPoint™ Application Programmatic Interface, Volume I 
provides a complete reference to the classes, messages, functions, and structures 
provided by the PenPoint Software Development Kit (SDK). 

The parts in the PenPoint API Reference axe organized in parallel with the parts in the 
PenPoint Architectural Reference (also available from Addison- Wesley). This volume 
contains datasheets on the APIs to the: 

PenPoint class manager 

PenPoint Application Framework™ 

Input subsystem and handwriting translation 

User interface toolkit 

Windows and graphics subsystem 

Other volumes in the GO Technical Library are: 

PenPoint Application Writing Guide provides a tutorial on writing PenPoint 

applications, including many coding samples. 

PenPoint User Interface Design Reference describes the elements of the PenPoint 

Notebook User Interface, sets standards for using those elements, and describes how 

PenPoint uses the elements. 

PenPoint Development Tools describes the environment for developing, 

debugging, and testing PenPoint applications. 

PenPoint Architectural Reference, Volume I presents the concepts of the fundamental 

PenPoint classes. 

PenPoint Architectural Reference, Volume //presents the concepts of the supplemental 

PenPoint classes. 

PenPoint API Reference, Volume //provides a complete reference to the supplemental 

PenPoint classes, messages, and data structures. 

GO Corporation was founded in September 1987 and is a leader in pen computing 
technology for mobile professionals. The company's mission is to expand the 
accessibility and utility of computers by establishing its pen-based operating system 
as a standard. 
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Can you design a lightweight, recyclable, 8 oz. 
plastic bottle that won'tbreak under moderate 
impact? I'll be travelling next week, but you 
can fax me suggested proposals at 21 3/ 
555-5833. 
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